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INDEX-1 


This manual describes RSTS/E special programming techniques, many of 
which are not available prior to Version 6 (RSTS/E) systems. Included 
in this manual are instructions and helpful hints for programming 
devices that RSTS/E supports. These technigues permit the programmer 
full control over input and output operations on specific devices; 
for this reason they are called device dependent operations. 


System accounts and the concept of privileged users are also 
discussed. Chapter 7, as it appeared originally in the RSTS/E System 
Manager's Guide, discusses SYS functions, both for privileged and for 
non-privileged users. 


The material covered in this manual assumes familiarity with the 


BASIC-PLUS Language Manual and _ the RSTS-11l System User's Guide, in 
addition to a thorough knowledge of the BASIC -PLUS language. For this 


reason, Senior Programmers and Application Programmers will be most 
interested in this manual. 


For information on all of the current manuals pertaining to RSTS/E 
Operation, consult the RSTS/E Documentation Directory. 
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CHAPTER 1 


DISKS 


1.1 SYSTEM ACCOUNTS 

RSTS/E systems have three system accounts which are essential to the 
operation of the system. The Master File Directory (MFD) account 
{1,1] is used on the system device and other disk devices in the 
system to control access. It is described in Section 1.1.1. The 
system library account [1,2] is used by the RSTS/E system to manage a 
library of generally available and restricted use system programs and 
message and control files. It is described in Section 1.1.2. System 
account [0,1] contains RSTS/E Monitor files and routines which are 
critical to the operation of the system. System account [0,1] is 
described in Section 1.1.3. 


1.1.1 MFD Account [1,1] On The System Device 


Access to the RSTS/E system is controlled by the use of 
project-programmer numbers and passwords. The system manager, 
Operating under his privileged account, creates a new account by using 
the system program REACT. The project-programmer number and password 
of the new account are given, along with other information, to allow a 
user access to system facilities. 


When a new account is created, the new account information is stored 
on the system device under the MFD account [1,1]. The password is 
stored in packed Radix-50 format. When the new user first creates a 
file, an area is created on the system device which is related 
directly to the user's account (project-programmer number). This area 
is called the User File Directory or UFD. The UFD contains 
information concerning the files created under that account number. 


The account [1,1] contains a catalog of information of all User File 
Directories on the system and is called the Master File Directory or 
MFD. When a user attempts to gain access to the RSTS/E system by 
giving his account and password, the system program LOGIN runs 
automatically. LOGIN checks the MFD on the system device to determine 
whether the account number and password given compare with one stored 
in the MFD. If so, the user is allowed access to the system. 
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Other account information is stored in the MFD for each account in the 
system. This information is summarized in Table 1-1. 


The account information in the MFD is accessed by various system 


programs. The LOGIN program has already been mentioned. The MONEY 
system program references the accumulated system accounting 
information. The system manager uses the MONEY system program to 


print and reset this accounting data. The disk storage information is 
referenced by the LOGOUT system program. The system manager can 
change the disk guota by use of the UTILTY system program. 


Table 1-1 
Account Information Stored in the MFD on the System Device 


Description Explanation 


Identification Project-programmer Refer to Chapter 9 of 


number (account) the BASIC-PLUS Language 
Manual. 


Password 6 characters stored within 
2 words in Radix-50 
format. 


Accumulated Central Processor Processor time the account 
Usage Unit (CPU) time has used to date in tenths 
(Run Time) of a second. 


Connect time Number of minutes the user 

(login time) has been connected to the 
system via a terminal or 
remote line. 


Kilo-core-ticks Core usage factor. One 

(KCT's) KCT is the usage of 1K 
words of memory for one 
tenth of a second. 


Device time Number of minutes of 
peripheral device time the 
account has used. 


Disk Storage Number of 256-word blocks 
the user is allowed to 
retain at log out time. 
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Using System Function calls, the system manager can write programs 
which access the information in the MFD. See the description of the 
system function calls in Chapter 7. 


1.1.1.1 MFD On Non-System Disks - The system disk exists in what is 
called the public structure. Additional disk devices can be added to 
the public structure or can be added as private packs. Each disk that 
is added to the system also contains its own MFD. The MFD of each 
additional disk is created when the system manager uses the 
initialization option DSKINT. The MFD of a disk contains account and 
storage information for that device only. 


The MFD on public disks is treated differently from the MFD on private 
disks. The RSTS/E system allocates space for a user's file on the 
disk in the public structure that has the most free space. If the 
user's account is not in the MFD of the disk with the most free space, 
his account number is added dynamically into the MFD of that disk and 
a UFD is created for the user on that disk. If a user desires to 
create a file on a private pack he cannot do so if his account number 
does not already exist in the MFD of that device. The system manager 
or a privileged user grants access to a private disk by entering the 
account information on the desired disk with the REACT system program. 


The MFD on a disk device contains that disk's pack label. The pack 
label information consists of pack cluster size, pack status (private 
Or public), and pack identification (id). The pack id is’ the 
6-character name in Radix-50 format given at the time the disk was 
initialized via the initialization option DSKINT. The pack id is 
utilized whenever the disk is logically mounted via the system program 
UTILTY or via INIT. (A distinction must be made between physical 
mounting and logical mounting. The disk is mounted physically by 
making the hardware ready to use the disk. The disk must be mounted 
logically by the system program UTILTY or UMOUNT or from commands in 
the START.CTL or CRASH.CTL files by the INIT system program. The disk 
must also be logically dismounted before it is physically dismounted 
to avoid corruption of the file structures.) 


1.1.2 System Library Account [1,2] 


The system library account [1,2] is created on the system device 
during the DSKINT operation of building the system disk. During the 
library build procedures, the system manager creates the contents of 
the system library account [1,2]. This section describes briefly the 
contents of account [1,2]. The entire content of the account is 


tabulated in the RSTS/E System Manager's Guide. 


The system library catalogs system programs which are available to 
general users and to privileged users. It also contains text and 
control files used by system programs. 


For operational purposes, the system library is accessed automatically 
during normal system start-up. As a result of specifying the START 
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option when RSTS/E is bootstrapped into memory, the console’ keyboard 
is logged in automatically under account [1,2]. At this time, the 
commands in the file START.CTL or in another command file, stored 
under account [1,2], are executed by the INIT system program, which is 
also stored under account [1,2]. Unless the system manager desires to 
modify or add to the contents of the system library after the system 
disk has been built, he should not log into the system under account 
[1,2]. 


For automatic restart purposes, the system library file CRASH.CTL is 
used by the INIT system program when recovering from system crashes. 
When automatic restart mode is entered, the RSTS/E system performs 
actions similar to those described above for normal start-up, except 
that the commands in the CRASH.CTL file are executed. 


Two files, HELP.TXT and NOTICE.TXT, are provided to supply information 
to the user. The HELP.TXT file is printed automatically by LOGIN if a 
user types HELP at a logged-out terminal. The NOTICE.TXT file is 
printed automatically by LOGIN after a user has typed a valid account 
number and password during the log-in procedure. The NOTICE.TXT file 
provides a means by which the system manager can communicate 
up-to-date installation information to users. Another system library 
information file, PIP.TXT, is printed out when the user types /HELP 
while running the related system program, PIP. 


The file GRIPE.TXT is created dynamically when a user runs the GRIPE 
system program. The system manager has read and delete access to the 
GRIPE.TXT file by means of the GRIPE system program. 


The file QUEUE.SYS is the system queue file and contains user requests 
created by the QUE program. The system queue manager program QUEMAN 
creates the file and initializes it. All spooling programs running on 
the system receive their requests from the QUEUE.SYS file through the 
QUEMAN program. 


The ERRLOG.FIL file contains a history of hardware errors logged on 
the RSTS/E system. The ERRCPY program transfers the error data from 
monitor storage to the file ERRLOG.FIL. The system manager gains 
information on its contents and deletes its contents by running the 
ERRDIS program. 


1.1.3 System Account [0,1] on the System Device 


The system account [0,1], like the system library account, is created 
on the system device during the DSKINT operation of building the 
system disk. Account [0,1] has a password identical to the pack id, 
and it contains name and retrieval information for system files. 
Account [0,1] is used solely by the RSTS/E Monitor to execute various 
operational and control actions. In this respect, it is a direct 
access account for use by the RSTS/E Monitor, and no user need be 
concerned with referencing its contents. This section describes the 
contents of the account, for a better understanding of the internal 
operations of the system. 
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The system manager creates and organizes the files stored under 
account [0,1] when he rebuilds the system disk using the REFRESH 
option. The possible contents of account [0,1] are described in the 
following paragraphs. 


1.1.3.1 Allocating Disk Storage Space ~ the file SATT.SYS is the 
mechanism by which RSTS/E controls the allocation and deallocation of 
storage space for the disk. The file maps the entire space on the 
disk in a bit map called a SAT (Storage Allocation Table). Each bit 
in a SAT represents either allocated or unallocated space. The system 
sets a bit in the SAT to 1 when that space is allocated for any 


purpose, 


The system allocates storage space in terms of clusters. Each bit in 
the SAT represents one cluster of disk space. A cluster is a fixed 
number of contiguous 256-word blocks of storage on the disk. The 
cluster size, or cluster factor, defines how many contiguous 256-word 
blocks are contained in the cluster. 


Cluster sizes in RSTS/E are defined for disks, directories, and files. 
Table 1-2 presents the types of clusters and related information. 


Table 1-2 
Valid Cluster Size Ranges 


Maximum 
Cluster Size Size When Defined 


Pack (for non- 1 (RF11/RK05) 16 (10) At initialization time 
system disk, 2 (RP02/RPO03) via DSKINT option 
public and 4(RP04) (stored in MFD) 
private) 


Directory (both Pack 16(10) At creation of the 

for MFD and Cluster directory via either 

UFD) Size the DSKINT 
initialization option, 
REACT, or SYS system 
function. 


Pack 256 (10) At creation of the file 
Cluster via either an OPEN or 
Size OPEN FOR OUTPUT. 
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The system manager specifies the cluster size of the disk when he 
initializes it and gives a value in response to the PACK CLUSTER SIZE 
question. The pack cluster size defines the number of contiguous 
256-word blocks a cluster comprises and, therefore, the extent of 
contiguous space represented by each bit in the SAT. A pack cluster 
size of 1 means that one 256-word block of storage is allocated for 
each bit set to 1. A pack cluster size of 2 means that two contiguous 
256-word blocks are allocated for each bit set to 1. Allowable pack 
cluster sizes for an RF or an RK type disk are l, 2, 4, 8, or 16; for 
an RPO2/RP03 type disk, 2, 4, 8, or 16; and for an RPO4 type disk, 4, 
8 or 16. 


The pack cluster size affects the efficiency of storage space 
allocation. A large size improves access time to system program and 
user files, but may waste disk space. For example, if the pack 
cluster size is 16, a one block file on the disk has allocated one 
cluster of 16 contiguous blocks. Fifteen blocks are wasted. A 15 
block file also requires one cluster but only one block is wasted. 
Thus, the system manager must choose the pack cluster size which best 
fits the type of processing and the access requirements of the local 
installation. 


A directory cluster size is defined for both a master file directory 
(MFD) and user file directory (UFD) and its minimum value is the pack 
cluster size. The system manager specifies the MFD cluster size when 
he initializes the disk; he specifies the UFD cluster size when he 
creates an account. A directory cluster size is equal to the pack 
cluster size or a power of 2 to a maximum of 16. Thus, for a pack 
cluster size of 2, the directory cluster size on that device can be 2, 
4, 8, or 16. For a pack cluster size of 8, a directory cluster size 
on that device can be 8 or 16. 


The directory cluster size limits the size to which a directory can 
expand. A directory, whether an MFD or a UFD, expands to catalog 
accounts or files but can occupy a maximum of seven clusters. For an 
MFD on the system disk, the cluster size determines how many accounts 
the system can handle. The following formula gives the number of user 
accounts, A, for each allowable MFD cluster size, MC. 


(217 x MC) - 1 
—_———----__—_——— = A 
2 


The minimum number of accounts (A) is 108 for an MFD cluster size of 1 
and the maximum is 1735 accounts for an MFD cluster size of 16. 


The UFD cluster size determines how many files a user can create under 
one account. The following formula gives the number of user files, 


UF, for each allowable UFD cluster size, UC. (The formula assumes 
that all files are a minimum size between 1 and 7 clusters.) 


(217 x uc) - 1 
3 
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The minimum number of user files (UF) is 72 for a UFD cluster size of 
1 and the maximum UF is 1157 for a UFD cluster size of 16. 


1.1.3.2 System Overlay File and DECtape Directory - The files OVR.SYS 
and BUFF.SYS are crucial to RSTS/E system response time. Optimum 
efficiency is gained when these files reside on a fast access, fixed 
head disk. If the system disk is not a fixed head disk, the system 
Manager can use the REFRESH option and cause a copy of the 
non-resident (overlay) code to be created, placed in the file OVR.SYS, 
and stored on the fast access disk, if available. On systems with 
only a moving head disk, it may be more efficient to create the file 
OVR.SYS and optimally position it. 


DECtape processing is expedited by the use of BUFF.SYS. When a file 
on DECtape is opened, the directory of the DECtape is written to the 
file BUFF.SYS. The BUFF.SYS file requires three 256-word blocks’ for 
each DECtape drive on the = system. Any updates to the DECtape 
directory which arise during processing cause the system to manipulate 
the copy in BUFF.SYS. This technique eliminates the need for 
continuous winding and rewinding of DECtape. The copy of the DECtape 
directory in BUFF.SYS is read back to the DECtape when the last file 
open on the DECtape unit is closed or any output file is closed. By 
use of the REFRESH option, the BUFF.SYS file can be placed on a fast 
access type disk or can be optimally positioned on the moving head 
system device. 


1.1.3.3 System Operations File - The RSTS/E Core Image Library 
resides in the file RSTS.CIL on the system disk. This file contains 
all executable code for system operations, resident and non-resident, 
and optionally contains the stand-alone program ROLLIN. 


1.1.3.4 Error Messages File - A copy of the BASIC-PLUS error messages 
from the CIL (RSTS.CIL) can be kept in the file ERR.SYS, which can be 
accecced wand modit ned. 


1.1.3.5 Saving Information After a Crash - The CRASH.SYS file can be 
created to retain a copy of valuable contents of memory at the time of 
a system crash. ; 


1.1.4 System Account [0,1] on Non-System Disks 


The system account [0,1] on non-system disks contains only a BADB.SYS 
file and a SATT.SYS file. The system account on non-system disks is 
created when the user initializes the disk. 
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1.2 PRIVILEGE 


Certain accounts in the RSTS/E system have special capabilities 
outlined in this section. An account having these special 
capabilities is called a privileged account. (In the same way, when a 
user is assigned a privileged account, he is a privileged user.) The 
system manager, operating under his own privileged account, designates 
other users as privileged by assigning them an account with a project 
number 1 when he creates it with REACT. The system library account 
[1,2], discussed in a preceding section of this section of his 
chapter, is an example of a privileged account. The available 
privileged account numbers are [1,3] through [1,254]. Privileged 
accounts have the following special capabilities: 


a. Unlimited file access. See Section 1.2.1. 


b. Creation and modification of privileged programs. See 
Section 1.2.2. 


c. Use of privileged aspects of system programs. See Section 
1.2.3. 


d. Use of privileged SYS functions and the PEEK function. See 
Chapter 7. 


The above listed capabilities are described in the remaining sections 
of this chapter and in Chapter 7. It must be emphasized that there is 
no fail safe and that no error messages are generated if the use of 
such special capabilities is to result in destruction of the system. 
For this reason, it is suggested that the system manager assign 
privileged accounts sparingly. It is recommended that the system 
Manager create additional non-privileged accounts for himself and 
perform most of his functions under them. The system manager should 
use a privileged account only when necessary. 


1.2.1 Unlimited File Access 


No file in the RSTS/E system can be protected against the user of a 
privileged account. A privileged user can create and delete files 
under any account number and can access files on LOCKED disks. Under 
such circumstances, no protection violation occurs. 


1.2.2 Creation And Modification Of Privileged Programs 


A program is privileged when it has a protection code of <192> or 
greater. Protection code <192> means that the privileged protection 
<128> and the compiled file protection <64> are set. Both protection 
code values must be set for a program to have privileged status. The 
system manager or privileged user designates a program as_ privileged 
by assigning to its compiled form a_ protection code of <192> or 
greater with the NAME-AS command. For example: 


NAME "FILE.BAC" AS "FILE.BAC <232>" 
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designates the compiled program FILE as privileged with write 
protection against the owner's group and all others not in the owner's 
group. Refer to Chapter 9 of the BASIC-PLUS Language Manual for the 
definition of protection codes. 

If a program is designated privileged, any user can run the program 
with privileged program status (provided he has READ access to the 
file). The privileged program status exists only for the duration of 
the program run. Privileged program status means that system 
operations normally reserved to a user of a privileged account can be 
executed while running under a non-privileged account. If the user 
running a privileged program interrupts execution of the program by 
typing CTRL/C, the program loses its privileged status. 


The ability to designate a program as privileged allows the system 
manager to extend use of privileged functions to non-privileged users. 
For example, the program TTYSET allows a user to change 
characteristics of his terminal. Such an action is a privileged 
system function executable only by owners of privileged accounts. 
With the privileged program status, execution of the function by the 
owner of a non-privileged account does not cause the normal program 
trap. 


The same TTYSET program additionally allows a privileged user to 
change characteristics of a terminal other than his own. A check is 
built into the program to ensure that a user attempting to change the 
characteristics of a terminal other than his own is indeed a 
privileged user. As a result, the execution of privileged functions 
is made available to the non-privileged user but some privileged 
features are restricted. The system manager likewise can control the 
use of privileged operations. 


1.2.3 Use Of Privileged Features Of System Programs 


The owner of a privileged account can execute the privileged features 
of system programs. Since the list of privileged features is lengthy, 
an entire chapter in the RSTS/E System Manager's Guide is devoted to 


7 mmvanm avomam anna MONEY 


explaining them. Certain programs, such as TTYSET, SYSTAT, and MONEY, 
are privileged but contain features helpful to the general user. 
These programs are therefore described in the RSTS-1l]1 System User's 
Guide for the non-privileged user. 


Two of the programs, TTYSET and MONEY, have privileged features about 
which the non-privileged user is not informed in the User's Guide. 
TTYSET is discussed in Chapter 4 of the RSTS/E System Manager's Guide. 
MONEY is discussed in Chapter 7 of this manual. Another program, 
SYSTAT, is discussed in Chapter 4 of the Manager's Guide and Chapter 7 
of this manual, although it contains few explicit privileged features. 
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1.3 NON-FILE STRUCTURED DISK OPERATION 


In non-file structured processing of disks, the user program can 
access specific physical blocks on the disk. The unit on which a disk 
is being processed in non-file structured mode may or may not be 
logically mounted. To initiate non-file structured processing, the 
program gives only a device designator in the OPEN statement. Of the 
three conventional forms of the OPEN statement, OPEN FOR INPUT, OPEN, 
and OPEN FOR OUTPUT, only two are valid. The following two sample 
statements, 


100 OPEN "DK1:" FOR INPUT AS FILE 1% 
and 
100 OPEN "DKl:" AS FILE 1% 


are equivalent statements because both reading and writing of physical 
blocks on the device are permitted. A third sample statement: 


100 OPEN "DK1:" FOR OUTPUT AS FILE 3% 
is invalid since it attempts to create a file. 


Subsequent to opening a disk device for non-file structured 
processing, GET and PUT statements can retrieve and write specific 
physical blocks on the device by means of the RECORD option. The 
record number is interpreted as a device cluster number. The device 
cluster size is the same as the minimum pack cluster size for that 
device type. The default buffer size is the device cluster size 
multiplied by 512 bytes. The following example reads the last 2 
blocks of an RPO3. 


100 OPEN "DP1:" AS FILE 1%8:GET #1%, RECORD 30000% + 9999% 


Device clusters are numbered starting at 0. Device cluster 0 can be 
accessed only immediately following an OPEN statement. The GET or PUT 
statement used to access device cluster 0 must either include RECORD 0 
or omit the RECORD option. Once device cluster 0 has been accessed, 
omitting the RECORD option or specifying RECORD 0 in a GET or PUT 
statement accesses the next sequential device cluster. The only way 
to access device cluster 0 again is to close the device and reopen it 
for non-file structured access. 


NOTE 


In file structured disk operations, file 
blocks are numbered form 1 to the last 
block of the file. A GET or PUT 
statement that omits the RECORD option 
or specifies RECORD 0 accesses the next 
sequential block in the file, since 
RECORD 0 of a file does not exist. 
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A user can access a disk in non-file structured mode without logically 
mounting it. The disk can be accessed by a user (either privileged or 
non~privileged) for reading and writing, once the disk is physically 
inserted in the disk drive. 


A non-privileged user cannot access a disk in non-file structured mode 
if some other user is accessing it. Attemping to access the disk 
under these condition results in a PROTECTION VIOLATION (ERR = 10) 
error for a non-privileged user. A privileged user can read the disk 
in non-file structured mode, regardless of how Many users are 
accessing the disk; but the privileged user cannot write on the disk 
in non-file structured mode if it is being accessed by another user. 


Once the disk is logically mounted, a privileged user is granted only 
read privileges in non-file structured mode. A non-privileged user is 
granted neither write nor read access in non-file structured mode, 
when the disk is logically mounted. 


1.4 UPDATE OPTION FOR DISK FILES 


In the description of disk files up to this point, the concept of 
Simultaneous user access to a single file has been largely ignored. 
The system permits several users to read from a single file 
simultaneously, but a problem arises when multiple users attempt to 
write onto a single file simultaneously. Two users could conceivably 
try to write the same record of the file, resulting in a loss of data. 
To avoid this conflict, the system normally permits Only one user ata 
time to have write privileges on any given file. Thus, a user may 
fail to obtain write privileges even if the file is not protected 
against writing. If this occurs the user must close the file and 
reopen it at a later time, after the other user has finished with the 
file and closed it. 


In certain applications (for example, sales order-entry applications) 
it might be normal for multiple users to be updating a single master 
file. In such cases it is not satisfactory to constantly close and 
reopen the file to obtain write privileges; this is a time-consuming 
operation. For this reason a special UPDATE option is available that 
permits muitiple users to have write access to a file while guarding 
against simultaneous writing of a single record. 


To indicate that a file is being opened for UPDATE, the MODE 13 
specification is used when the file is opened. For example; 


100 OPEN "MASTER" AS FILE 1%, MODE 13 


when used with a disk file indicates that the file is opened for 
UPDATE (1). 


In this case the program is granted write privileges 


(1)The RECORDSIZE option may not be used on files that are opened for 
UPDATE because only one block (512 bytes) can be locked on a given 
channel at a time by a user. 
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unless such access is specifically prohibited by the protection code 
of the file. 


A file cannot be simultaneously open for UPDATE by one user and open 
in normal (non-UPDATE) mode by another user. Attempting to open a 
file for UPDATE if it is already open in normal mode, or attempting to 
open a file in normal mode if it is already open for UPDATE, results 


in a PROTECTION VIOLATION error. 


Once a file has been opened for UPDATE, any _ read operation of a 
specific record puts that block in a special "locked" state. This 
means that no other user is permitted to read or write that record 
until it is released (or unlocked) by the program that locked it. 
Attempting to read or write a record that another user has_ locked 
results in a DISK BLOCK IS INTERLOCKED (ERR = 19) error which can be 
trapped with an ON ERROR GOTO command. There are five ways for a 
program to unlock the record: 


1. The next write operation on the file unlocks the record. 


2. Executing an UNLOCK statement. This statement has the form: 


where <expr> is the internal channel number of the file that 
is opened for UPDATE. 


3. Any error encountered while accessing the file unlocks’ the 
RECORD. 


4, Reading another record unlocks the currently locked record. 
Any read operation locks the record just retrieved. 


5. Executing a CLOSE statement on the file unlocks the record. 
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To illustrate UPDATE, consider a simple inventory application where 
operators on several terminals can access one file to enter a part 
number and order quantities. Assume that the file is sequenced so 
that each part number actually corresponds to the record number that 
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contains information about the part, and that the first four 


characters of the 512-byte record contain the quantity available as a 
(2-word) floating-point number. For this example, the remaining 508 
characters are ignored. A program to update the quantity available is 
as follows: 


100 ON ERROR GOTO 1000 !FIND OUT ABOUT ERRORS 
200 OPEN “INVENT.ORY" AS FILE 1, MODE 1 !OPEN FILE IN UPDATE MODE 
300 FIELD #1, 4 AS CS !cS IS QTY IN FILE 
400 INPUT "PART NUMBER";N; "QUANTITY";Q !IGET PART # AND QTY 
500 GET #1, RECORD N !READ APPROPRIATE RECORD 
600 X=CVTSF(CS$)-Q !COMPUTE QTY REMAINING 
700 IF X>=0 THEN 800 ! ENOUGH ON HAND? 
710 UNLOCK #1 !PERMIT OTHER ACCESSES 
720 PRINT "ONLY" CVTSF(CS) “ITEMS LEFT" !REPORT STOCK LEVEL 
730 GOTO 400 !REVISE ORDER? 
800 LSET CS=CVTFS (X) ISTORE NEW QTY ON HAND 
850 PUT #1, RECORD N !REWRITE INTO FILE 
900 GOTO 400 !NEXT TRANSACTION 
1000 IF ERR <>19 THEN ON ERROR GOTO 0 ! IGNORE NON-INTERLOCK 

! ERRORS 
1100 PRINT "WAITING" !LET HIM KNOW WE'RE HERE 
1200 SLEEP 5 !WAIT FOR CURRENT ACCESS 
1300 RESUME 500 !'TRY AGAIN 
1400 END 


A privileged user can write into a UFD/MFD only by using MODE 16384% 
in the OPEN statement. For example, 


OPEN "DK1:[5,10]" AS FILE 2%, MODE 16384% 


allows a privileged user to read and write into the UFD of account 
[5,10]. 


Specifying MODE 5% (1%+4%) in an OPEN statement requires a record to 
be already locked (via a previous GET statement) for a PUT statement 
to be executed. If the record is not locked, attempting to execute 
PUT results in a PROTECTION VIOLATION (ERR = 10) error. 


1.5 APPENDING DATA TO A DISK FILE 


To write data to a new block following the current end of file in a 
disk file, specify the MODE 2% option in the OPEN statement. Mode 2% 
should be used only with Record I/O files. For example, 


100 OPEN "DATA" AS FILE 1%, MODE 2% 


The system opens the file DATA under the current account on the system 
disk. The next output operation creates a new block and appends it to 
those currently allocated to the file. Any fill characters in the 
previous last block of the file remain when the system appends the new 
last block. Do not use the OPEN FOR OUTPUT form of the OPEN 
statement, as it deletes the existing file. 
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1.6 FLOPPY DISKS 


The RX11/RX01 Floppy Disk can be used only as a non-file structured 
device. The device name for the floppy disk is DX. Unit numbers for 
the floppy disk drive start at 0. The current floppy disk 
implementation allows only a single .BAS file to be stored on floppy 
disk unit 1, for example, with the SAVE command: 


SAVE DXI1: 


It can be read from the disk or run by the following respective 
commands: 


OLD DXl: 
and 
RUN DXl: 
A floppy disk is divided into 77 tracks (numbered 0 through 76), each 
of which consists of 26 sectors (numbered 1 through 26). 
Consequently, there are 2002 (77 x 26) 128-byte records (numbered 0 
through 2001) on each disk. 


A floppy disk can be opened and accessed in either of two modes: 
sector mode or block mode. 


1.6.1 Sector Mode 


In sector mode the buffer size is 128 bytes. Open the floppy disk on 
unit 3 in sector mode with the following statement: 


OPEN "DX3:" AS FILE 1%, MODE 16384% 


When the GET and PUT statements are used, track and sector numbers can 
be calculated once the RECORD number is known. If the desired record 
number is specified as N (any number from 0 through 2001), the track 
and sector accessed can be determined as follows: 


TRACK = INT (N/26) 

SECTOR = N - INT(N/26)*26 + 1 
A GET statement reads a 128-byte record from the disk. The RECORD 
option, if present, defines a specific record on the disk. If the 


RECORD option is omitted or RECORD 0% is included, the next sequential 
record is read. 


100 GET #1%, RECORD N% 
In the above statement, N% is the record number and can be any number 


from 1 through 2001. (Record 0 can be accessed only by the first GET 
statement after the file has been opened.) 
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If -32768% (formed by 32767% + 1%) is included in the RECORD option 
(e.g., RECORD N%-32767%-1%), sectors are interleaved according to the 
algorithm discussed in Section 1.6.2. 


A PUT statement writes 


a 128-byte r 


200 PUT #1%, RECORD N%, COUNT C% 


In the above statement, N% is the record number. The RECORD option 
can also include -32768% for interleaving (see Section 1.6.2) and 
16384% to write a Deleted Data Mark with each of the records (see 
Section 1.6.3). C% must be a multiple of 128. 


1.6.2 Block Mode 


In block mode the buffer size is 512 bytes, equivalent to four 
128-byte records. The four sectors are interleaved according to the 
following algorithm where N is the value specified in RECORD: 


TEMP] = INT(N/26) 

TEMP2 = N - INT(N/26) *26 
TEMP2 = TEMP2 * 2 

TEMP2 = TEMP2+1 IF TEMP2 >=26 
TEMP2 = TEMP2 + 6*TEMP1 

TRACK = TEMP] + 1 


SECTOR = TEMP2 - INT (TEMP2/26)*26 + 1 


The above interleaving algorithm is standard for other PDP-1l 
Operating systems for the floppy disk (e.g., RSX-11M, RT11). Track 0 
is unavailable in order to reserve its use for IBM-compatible labels. 


The statement shown below opens the floppy disk on unit 3 in block 
mode on I/O channel l. 


OPEN "DX3:" AS FILE 1% 


A GET statement reads a 512-byte block from the disk. The RECORD 
option, if present, defines a specified sector starting point for the 
read. If the RECORD option is omitted or RECORD 0% is included, the 
next sequential block is read. 
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100 GET #1%, RECORD N% 


In the above statement, N% is the number of the sector at which the 
block begins. It can be any number from 1 through 493. (The first 
block on the disk can be accessed only by the first GET statement 
after the device is opened.) 


A PUT statement writes a 512-byte block on the disk. 
200 PUT #1%, RECORD N%, COUNT C% 


In the above statement, N% is the number of the sector at which the 
block begins. It can also include 16384% to write a Deleted Data Mark 
with each of the sectors (see Section 1.6.3). C% must be a multiple 
of 128. 


Block mode operations can be performed in sector mode by opening the 
disk with this statement: 


OPEN "DX3:" AS FILE 1%, RECORDSIZE 512%, MODE 16384% 
and using the GET (or PUT) statement as follows: 
GET #1%, RECORD N&*4% + 32767% + 1% 


In the above statement, 32767% + 1% specifies sector interleaving and 
N%*4% defines 512-byte blocks at 4-sector intervals. 


1.6.3 Deleted Data Marks 


Each sector of a floppy disk contains a bit called the Deleted Data 
Mark, in addition to its 128 bytes of data. When an INPUT or GET 
operation from the disk encounters a Deleted Data Mark, the DATA 
FORMAT ERROR (ERR = 50) occurs. 


In the case of a GET operation, the contents of the buffer are valid 
even if this error occurs. So it is possible to examine the contents 
of the record containing the Deleted Data Mark. When the recordsize 
specified is larger than 128 bytes (e.g., block mode operation), the 
last 128 bytes read into the buffer are the data that had the Deleted 
Data Mark. The RECOUNT variable reflects the amount of data read up 
to and including this mark. 
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The devices shown below have the following default characteristics: 


Device 


Device 
Clustersize 


Default Buffer Maximum 
Size (non-file Record No. 


structured) in 
Bytes 


RECORD 
RECORD 
RECORD 
RECORD 
RECORD 


(#platters*1024)-1 
4799 

39999 

41799 

2001 


CHAPTER 2 


MAGTAPE 


Magtape I/O is processed under RSTS-ll in on of two forms: file 
structured magtape and non-file structured magtape. In addition to 
this distinction, RSTS/E supports magtape files both in DOS-11l and in 
ANSI formats. (See Appendix A for detailed information on DOS vs. 
ANSI magtape file labels.) 


NOTE 


For accurate results, all files stored 
on a given magtape should be written in 
the same format (DOS-11l or ANSI). 
Mixing file types on one tape can result 
in illogical interpretations. 


A user program controls file structured magtape operations by the MODE 
specification in the OPEN statement. MODE determines how the system 
searches for a file with each of the three forms of the OPEN statement 
described in Section 9.2 of the BASIC-PLUS Language Manual. It also 
controls the system action when the file is subsequently closed. 


The following sections describe magtape operations in some detail. 
Sections 2.1 through 2.3 describe the use of MODE with each of the 


ea 9 AA th - a aArakian 
forms of the OPEN statement. Section 2.4 describes magtape operation 


on a CLOSE statement. The remainder of this chapter discusses 
non-file structured magtape operations, the MAGTAPE function, and 
error handling techniques. 


2.1 THE FILE STRUCTURED MAGTAPE OPEN FOR INPUT 


Once a filename is specified in the OPEN statement, that magtape file 
is opened for file structured processing. For example: 


100 OPEN "MTOQ:ABC" FOR INPUT AS FILE N%, MODE M% 


The OPEN FOR INPUT statement searches for a specified file on a 
designated magtape unit. A BASIC-PLUS program executes the statement 
so that it can subsequently perform input from the file. (Unlike disk 
operation, OPEN FOR INPUT on magtape permits read access only.) 
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In the above example, the system associates magtape unit 0 with the 
channel designated by N% and searches for file ABC under the current 
account according to the value of M% in the MODE specification. 


The meanings shown below can be attached to MODE values used in an 
OPEN FOR INPUT statement. The MODE value can be the sum of any 
combination of these single values, as long as they are not mutually 
exclusive. 


MODE Meaning 
0% Read record at current tape position. 
2% Do not rewind tape when searching for specified file. 
32% Rewind tape before searching for specified file. 
64% Rewind tape upon executing a CLOSE. 
16384% Search for a DOS formatted label. 
24576% Search for an ANSI formatted label. 


If the file is found, it is open for read access only. A GET 
statement subsequently executed on channel N% makes a block of the 
file available to the program in the channel's buffer. Since the file 
is open solely for input, a PUT statement subsequently executed on the 
channel generates the PROTECTION VIOLATION error (ERR = 10). If the 
system detects a logical end of tape before finding a file, the CAN'T 
FIND FILE OR ACCOUNT error (ERR = 5) occurs. 


To open a file stored on the magtape under an account other than the 
current account, simply supply the proper project-programmer number in 
the OPEN statement. Since the system does not check protection codes 
for files on magtape, any user can access a magtape file. 


2.1.1 Searching For A Record 


Omitting the MODE specification or using a MODE 0% specification reads 
the record at the current position of the tape. If the system finds a 
label record and its file name and account match those of the file 
specified in the OPEN statement, the system generates the NAME OR 


ACCOUNT NOW EXISTS error (ERR = 16). No match causes the system to 
rewind the tape and check successive label records until the record is 
found or the logical end of tape is detected. The system does not 


rewind the tape when the program executes a CLOSE statement on channel 
N%. 


2.1.2 Rewinding The Tape 


As mentioned before, MODE 0% reads the tape from its current position. 
If the filename specified in the OPEN statement does not match the 
record label, the system automatically rewinds the tape to the first 
label record and begins reading labels file by file. 


To override this automatic rewind feature, include the MODE value 2% 
in the OPEN statement. In this case, the system reads the tape from 
its current position and, if no match occurs, continues reading label 
records from that position forward until either the file is found or 
until the logical end of tape is detected. The system normally does 
not rewind the tape when it performs a CLOSE operation. 
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MODE 32% rewinds the tape to the first label record before reading any 
label. Once again, no match causes the system to check successive 
label records until the file is found or until the logical end of tape 
is detected. The system does not rewind the tape when it performs the 
CLOSE operation on channel N%. Finally, including MODE value 64% 
rewinds the tape when a CLOSE statement is executed on channel N&. 


2.1.3 DOS and ANSI Format Labels 


Including MODE 16384% in the OPEN FOR INPUT statement searches for the 
Magtape file whose filename is specified. In addition, the file must 
be written in DOS format (i.e., preceded by a DOS label) for the 
search to be considered successful. 


When the user omits the MODE value 16384%, the system assumes’ record 
labels on the tape, either DOS or ANSI, are in the default format 
specified by the system manager when he starts time-sharing 
operations. The default format can also be defined with an ASSIGN 
statement. 


Including MODE 24576% in the OPEN FOR INPUT statement searches for the 
magtape file whose filename is specified. In this case, the file must 
be written in ANSI format (i.e., preceded by an ANSI label) for the 
search to be considered successful. 


The system reads the tape at its current position. If the file is not 
found, it rewinds the tape and reads label by label until it finds the 
correct file. If the logical end of tape is detected, the CAN'T FIND 
FILE OR ACCOUNT error (ERR = 5) occurs. 


Once again, omitting the MODE value 24576% in the OPEN FOR INPUT 
statement assumes record labels are in the format originally specified 
by the system manager. 


2.1.4 Example of OPEN FOR INPUT Statement 


The values for MODE discussed above can be combined in any combination 
as long as they are not mutually exclusive. (For example, MODE 16384% 
is incompatible with MODE 24576%, so MODE 16384%+24576% causes 
illogical results.) 


Consider the following line: 
10 OPEN "MT1:MARKIE" FOR INPUT AS FILE 3%, MODE 24772% 


This line opens the file MARKIE on magtape unit 1 and associate it 
with channel 3%. MODE 24772% is actually the sum of MODE 
32% + 64% + 24576%. 


When the above line is executed, the system rewinds the tape to. the 
first record label (MODE 32%) and begins to read successive record 
labels until the file is found or the logical end of tape is reached. 
The search is successful only if the system finds the file MARKIE, 
written in ANSI format (MODE 24576$%). 
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When the search is successful, the file MARKIE is available for input, 
via GET statements. Remember, since the file is open for input only, 
attempting to execute PUT statements results in a PROTECTION VIOLATION 
error. 


A subsequent CLOSE statement rewinds the tape (MODE 64%). 


2.2 THE FILE STRUCTURED MAGTAPE OPEN FOR OUTPUT 


The OPEN FOR OUTPUT statement searches for a specified file on a 
designated magtape unit. A BASIC-PLUS program executes the statement 
so that it can subsequently perform output to the file. For example: 


10 OPEN "MTO:ABC" FOR OUTPUT AS FILE N%, MODE M% 


The system associates magtape unit 0 with the internal channel 
designated by N% and searches for the file ABC on the current account 
according to the value M% in the MODE specification. 


If the file is not found, the system writes a magtape label record for 
the file at the logical end of tape and leaves the unit open with 
write access only. A PUT statement subsequently executed on channel 
N% writes the channel's buffer to the magtape. Since the file is open 
solely for output, a GET statement executed on channel N% generates 
the PROTECTION VIOLATION error (ERR = 10). 


The search is successful when the specified file is located. The 
value of M% in the MODE specification determines how the system 
searches for the file and acts upon the file when it is found. The 


following meanings can be attached to the MODE values used in an OPEN 
FOR OUTPUT statement. The MODE value used can be the sum of any 
combination of these single values, as long as they are not mutually 
exclusive. 


MODE Meaning 
0% Read record at current tape position. 
2% Do not rewind tape when system searches for the 


Magtape file. 


16% Write over existing file. (Destroy any subsequent 
files currently on the tape.) 


32% Rewind tape before searching for the magtape file. 
64% Rewind tape upon executing the CLOSE statement. 
128% Open for append. 
512% Write new file label group without searching. 
16384% Search for a DOS formatted label. 
24576% Search for an ANSI formatted label. 
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2.2.1 Searching for a Record 


Omitting the MODE specification or using a MODE 0% specification reads 
the tape at its current position. If the system finds a label record 
and its file name and account match those of the file specified in the 
OPEN statement, the system generates the NAME OR ACCOUNT NOW EXISTS 
error (ERR = 16). No match causes the system to rewind the tape and 
to check successive magtape label records until either a match is made 
or until the logical end of tape is detected. If the system detects 
the logical end of tape, the search is unsuccessful. As a result, the 
system backspaces over the logical end of tape, writes a label record 
for the file, and allows write access to the file. The system does 
not rewind the tape when the program executes a CLOSE statement on 
channel N%. 


2.2.2 Writing A Record 


As mentioned before, a search is successful when the system finds’ the 
specified file on the magtape. The NAME OR ACCOUNT NOW EXISTS error 
occurs when this happens. This is a precaution to prevent the user 
from writing a file at this point. (Doing so will write over the 
current file and erase all subsequent files on the tape.) A value of 
16% included in the MODE specification suppresses this error message 
and causes the system to write over an existing file on magtape. 


NOTE 


MODE 16% causes any files following the 
overwritten file to be lost. 


When 16% appears alone in the MODE specification, the system initially 
reads the magtape at its current position. If the system finds a 
label record and the file name in the label record matches the file 
name in the OPEN FOR OUTPUT statement, it backspaces over the label 
record, writes a new label record over the existing label and allows 
the user program write access to the file. If the logical end of tape 
is at the current position, the system backspaces one record and 
writes a new label record and allows write access to the file. No 
match causes the system to rewind the tape and to check label records 
until either the file is located or until the logical end of tape is 
detected. Detecting the logical end of tape before locating the file 
causes the system to backspace one record and write a tape label for 
the file and to allow the user write access to the file. 


A CLOSE statement for a magtape open with MODE 16% writes trailing EOF 
records, backspaces two records, but does not rewind the tape. 


When 512% is included in the value for the MODE option, the system 
writes a label record at the current tape position. No label record 
reading occurs. The system simply writes a new label record, erasing 
all subsequent files on the tape. Only the value 32%, which causes 
the tape to rewind (see Section 2.2.4), takes precedence over 512%. 
Therefore, when 512% is used in conjunction with any combination of 
values, not including 32%, the system writes a record label at the 
current tape position. 


NOTE 
Any MODE value which includes 512% 
causes files following an overwritten 
file to be lost. The overwritten file 
is always the one at which the tape is 
currently positioned except when 32% is 
also included in the MODE value. 


The FILESIZE and CLUSTERSIZE options have effect only when the file 
specified in the OPEN FOR OUTPUT statement is in ANSI format. The 
general form of this statement with options is: 


OPEN "MTOQ:ABC" FOR OUTPUT AS FILE N%, FILESIZE P%, 
CLUSTERSIZE Q%, MODE M% 


The system associates magtape unit 0 with the internal channel 
designated by N%. The value P% in the FILESIZE option designates the 
block size and the value Q% in the CLUSTERSIZE option designates the 
record size, format and file characteristics. See Section 2.8.8 for 
explanations of format and file characteristics. 


2.2.3 Extending A File 


When 128% is included in the value for the MODE option, the system 
attempts to open an existing file and append information to it. The 
file must already exist; if it does not exist, a CAN'T FIND FILE OR 
ACCOUNT error (ERR = 5) occurs. The file must also be the last file 
on the tape before the logical end of tape. If it is not the last 
file on the tape, the system cannot locate the trailing EOF records 
and a PROTECTION VIOLATION error (ERR = 10) occurs. As is the case 
for all other MODE option values, 128% can be used alone or in 
conjunction with any combination of values. 


2.2.4 Rewinding The Tape 


As mentioned before, MODE 0% reads the tape at its current position. 
If the file name specified in the OPEN statement does not match the 
record label, the system automatically rewinds the tape to the first 
record label and begins reading labels file by file. 


To override this automatic rewind feature, include the MODE value 2% 
in the OPEN statement. In this case, the system reads the tape from 
its current position and, if no match occurs, continues reading label 
records from that position forward until either the search is 
successful or until the logical end of tape is detected. The system 
does not rewind the tape when it performs a CLOSE operation. MODE 32% 
rewinds the tape to the first record label before reading any label. 
Once again, no match causes the system to check successive label 
records until the file is found or until the logical end of tape is 
detected. The system does not rewind the tape when it performs the 
CLOSE operation on channel N%. 
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Finally, including MODE value 64% rewinds the tape when a CLOSE 
statement is executed on channel N&. 


2.2.5 DOS and ANSI Format Labels 


Including MODE 16384% in the OPEN FOR OUTPUT statement searches for a 
magtape file whose file name is specified. In addition, the file must 
be written in DOS format (i.e., preceded by a DOS label) for the 
search to be considered successful. 


When the user omits the MODE value 16384%, the system assumes'- record 
labels on the tape, either DOS or ANSI, are in the format specified by 
the system manager when he starts time-sharing. 


Including MODE 24576% in the OPEN FOR OUTPUT statement searches for 
the magtape file whose file name is specified. In this case, the file 
must be written in ANSI format (i.e., preceded by an ANSI label) for 
the search to be considered successful. If the file is found, the 
system returns the NAME OR ACCOUNT NOW EXISTS error (ERR = 16). 


The system reads the tape from its current position. If the file is 
not found, it rewinds the tape and reads label by label until it finds 
the correct file. If the logical end of tape is detected, the system 
automatically backspaces over two EOF records, writes an ANSI label 
record for the file, and allows write access to the file. 


Once again, omitting the MODE value 24576% in the OPEN FOR OUTPUT 
statement assumes record labels are in the default format originally 
specified by the system manager. 


2.2.6 Example Of OPEN FOR OUTPUT Statement 


The values for MODE mentioned above can be combined in any combination 
as long as they are not mutually exclusive. Consider the following 
line: 


10 OPEN "MT0:LLL317" FOR OUTPUT AS FILE 2%, MODE 16466% 
This line opens the file LLL317 on magtape unit 0 and associates it 


with channel 2%. MODE 16466% is actually the sum of MODE 
2% + 16% + 64% + 16384%. 
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When the above line is executed, the system determines whether’ the 
current record label is in DOS format (MODE 16384%). If the file is 
not found, the system does not rewind the tape (MODE 2%), but instead 
continues to search for labels in DOS format from the next record on. 
If the correct label record is found (i.e., LLL317 exists), the system 
backspaces one record and writes the new label over the existing label 
(MODE 16%). If the logical end of tape is found first, the system 
backspaces one EOF record and writes the new label, allowing write 
access to the new file. 


Once the new record label is written, the file LLL317 is available for 
output, via PUT statements. Remember, since the file is open for 
output only, attempting to execute GET statements results in a 
PROTECTION VIOLATION error. 


A subsequent CLOSE statement rewinds the tape (MODE 64%). 
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2.3 THE FILE STRUCTURED MAGTAPE OPEN 


The OPEN statement performs an OPEN FOR INPUT operation for a 
designated file on a specific magtape unit. For example, 


10 OPEN "MTO:ABC" AS FILE N%, MODE M% 


The system associates magtape unit 0 with the internal channel 
designated by N% and searches for the file ABC on the current account 
as if an OPEN FOR INPUT statement were specified with M% in the MODE 
specification. An OPEN statement without a MODE specification is 
treated as if MODE 0% had been given. If the OPEN FOR INPUT operation 
succeeds, the program has read access to the file on the channel's 
buffer. 


An unsuccessul OPEN FOR INPUT operation causes the system to perform 
an OPEN FOR OUTPUT operation using the MODE M% specification. The 
OPEN statement is not a recommended method for processing magtape 
since the program cannot immediately determine which type of OPEN 
statement was executed. 


2.4 THE FILE STRUCTURED MAGTAPE CLOSE 


The CLOSE statement terminates processing of a magtape file. If the 
file is open for input, the system skips to the end of the file (if it 
is not already there), and frees the buffer space for other usage 
within the program. If the file is open for output and the file label 
is in ANSI format, the system writes a trailer label group (see 
Appendix A). The system writes three EOF records to mark the logical 
end of tape, regardless of the file label format. It then backspaces 
the tape over two of the EOF records to position the tape for 
subsequent output, and frees the buffer space for other usage within 
the program. 


Additionally, the system rewinds the tape if the value 64% was 
included in the MODE specification. Unless 64% is specified, the 
system does not rewind the tape. 


2.5 THE NON-FILE STRUCTURED MAGTAPE OPEN 


In non-file structured processing there are no special file label 
records written on the tape. Essentially, the system passes the data 
directly between the magtape and the user program. Tapes of any 
format can be read or written with non-file structured magtape 
operations, as long as the program is set up to handle the actual tape 
format correctly. Only records 14 bytes or longer can be accessed. 
Attempting to write a record shorter than 14 bytes results in the 
ILLEGAL BYTE COUNT FOR I/O error (ERR = 31). 


In the OPEN statement, only the magtape unit is specified to indicate 
non-file structured processing; no filename is included. There are 
three types of OPEN statements, as before. These are: 

100 OPEN "MTO:" FOR INPUT AS FILE 1% 


or 


100 OPEN "MTO:" AS FILE 1% 
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OPEN FOR INPUT and the simple OPEN statements are equivalent. No 
magtape movement occurs and both reading and writing of records is 
permitted. The third form is slightly different: 


100 OPEN "MTO:" FOR OUTPUT AS FILE 1% 


In this example, the OPEN FOR OUTPUT permits writing only. This is 
the normal way of opening a magtape for writing. 


2.6 THE NON-FILE STRUCTURED MAGTAPE CLOSE 


CLOSE has no special action on non-file structured magtapes unless 
OPEN FOR OUTPUT was used. On a magtape that was OPEN FOR OUTPUT, the 
CLOSE statement causes trailer EOF records to be written, followed by 
backspacing over two of these EOF's, to position the tape correctly 
for subsequent output operations. 


In any case, if the magtape was open for non-file structured 
processing, it is not rewound on CLOSE. 


2.7 THE MODE SPECIFICATION IN NON-FILE STRUCTURED PROCESSING 
The MODE specification with non-file structured magtape processing can 
be used with either 7-track or 9-track devices. When used with 
7-track drive, MODE indicates both tape density and parity. When used 
with a 9-track TU1O drive, MODE indicates parity only, since a 9-track 
TU10 drive reads and writes only at 800 BPI. When used with a 9-track 
TU16 drive, MODE also can indicate 1600 BPI phase encoded mode. 
MODE in the OPEN statement is evaluated by the following algorithm: 
MODE E+D*4+P 
where: 
E (phase encoded) in bits per inch (BPI) is: 


256 
0 


1600 BPI, phase encoded mode 
values of D and P (see below) 


D (density) in bits per inch (BPI) is: 


200 BPI (7-track only) 
556 BPI (7-track only) 
800 BPI (7-track only) 
800 BPI, dump mode 


WNHHO 


P (parity) is: 


0 
1 


odd parity 
even parity 
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If mode is not specified in the OPEN statement, the tape is processed 
in odd parity at 800 BPI dump mode, or with a MODE of 0%+3%*43+03. 


Dump mode indicates that the system dumps from memory the actual 
representation of the data. Since there are 8 bits in one PDP~1l 
byte, 9-track drives, which have 8 data tracks, always operate in dump 
mode. For a 7-track drive, which contains space for only six data 
bits per frame, the dump mode means one PDP-1l 8-bit byte is written 
to and read from two frames on the tape. The system uses one tape 
frame to hold bits 0 through 3 of a byte and a second frame to hold 
bits 4 through 7 of the byte. 


Other values for density are in non-dump mode and apply only to 
7-track drives. On output operations, the system writes bit 0 through 
5 of each PDP-1l 8-bit byte to a frame on the tape. Two bits, 6 and 
7, are lost on each write operation. On input operations, the system 
transfers the data bits of a frame into bits 0 through 5 of a PDP-ll 
byte and sets bits 6 and 7 to zero. In this manner, bit formats other 
than the 8-bit byte format can be read from and written to 7-track 
magtape. 


Effectively, MODE for a 9-track TU10 drive can only be a 0 or 1 since 
the system operates at 800 BPI dump mode with 9-track TU10 drives. If 
any other values are used, the system recognizes only the parity 
specification. 


MODE for a 9-track TU16 drive can indicate 1600 BPI phase encoded 
operation. Parity is always odd for phase encoded operation. 


To allow read and write access to a tape, use the OPEN or OPEN FOR 
INPUT statement. For example: 


OPEN "MTO:" AS FILE 1%, MODE 5% 


or 
OPEN "MTO:" FOR INPUT AS FILE 1%, MODE 5% 


Either statement makes the tape on the 7-track drive (set at unit 0) 
available for execution of GET and PUT statements on channel 1%. The 
system accesses tape with a density of 556 BPI and even parity. The 
system performs no tape positioning nor status checking. The user 
must perform such operations using the MAGTAPE function described in 
Section 2.8. 


To allow only write access to a tape, use the OPEN FOR OUTPUT. For 
example: 


OPEN "MT1l:" FOR OUTPUT AS FILE 1%, MODE 12% 


If the unit is write locked (the write enable ring on the reel is 
missing), the system generates the DEVICE HUNG OR WRITE LOCKED error 
(ERR = 14) and does not open the device. Otherwise, the statement 
makes the tape on unit 1 available for execution of PUT statements on 
channel 1%. Since the device is open solely for write access, an 
attempt to execute a GET statement on the channel causes the 
PROTECTION VIOLATION error (ERR = 10). The system writes records in 
odd parity at a density of 800 BPI, dump mode. The user program must 
check the status of the device and control the device by use of the 
MAGTAPE function described in Section 2.8. 
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To read and write records larger than 512 bytes on magtape, include 
the RECORDSIZE option in the OPEN statement as described in the 
BASIC-PLUS Language Manual in Section 9.2.1. Subsequent GET 
operations read records of maximum size equal to RECORDSIZE. RECOUNT 
contains the actual number of bytes read. PUT operations which are 
not modified by the COUNT modifier write records whose size is 
specified in the RECORDSIZE option. 


To write records smaller than 512 bytes, use the COUNT option 
described in the BASIC-PLUS Language Manual in Section 12.3.2. If 
smaller records are read, the RECOUNT variable contains the number of 
bytes. 
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2.8 THE MAGTAPE FUNCTION IN NON-FILE STRUCTURED PROGRAMMING 
The MAGTAPE function provides flexibility in non-file structured 
processing by permitting the program control over all magtape 
functions. The general form of the MAGTAPE function is as follows: 

I% = MAGTAPE (F%,P%,U%) 
where: 

FS is the function code (1 to 9) 


P& is the integer parameter 


U% is the internal channel number on which the’ selected 
Magtape is open 


Is is the value returned by the function 


The effect of the MAGTAPE function is determined by the function code, 
FR. These functions are described in the sections that follow. In 
all examples in these sections, assume that magtape unit 1 has been 
opened on internal channel 2. That is, prior to executing the MAGTAPE 
function, the following statement was executed. 


100 OPEN "MT1:" AS FILE 2% 


The following discussion of each of these functions includes the word 
IMMEDIATE or WAIT. IMMEDIATE indicates that the monitor initiates the 
action and returns control to the program immediately; WAIT indicates 
that the program must wait for the operation to be completed before 
continuing. 


2.8.1 Off-Line (Rewind and Off-Line) Function 


IMMEDIATE 
Function code =] 
Parameter = unused 
Value returned = 0 


The Off-Line function causes the specified magtape to be rewound and 
set to OFF-LINE (thus clearing READY). For example: 


200 I = MAGTAPE (1%,0%, 2%) 


rewinds and sets the magtape open on internal channel 2 to OFF-LINE. 


2.8.2 WRITE End-of-File Function 


WAIT 
Function code = 2 
Parameter = unused 
Value returned = 0 
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The WRITE End-of-File function writes one EOF record at the current 
position of the magtape. For example: 


200 I% = MAGTAPE (2%,0%,2%) 


writes an EOF on the magtape that is open on internal channel 2. 


2.8.3 Rewind Function 


IMMEDIATE 
Function code = 3 
Parameter = unused 
Value returned = 0 


The Rewind function rewinds the selected magtape. For example: 
200 I% = MAGTAPE (3%,0%,2%) 


rewinds the magtape open on internal channel 2. (This function does 
not cause the magtape to be set to OFF-LINE.) 


2.8.4 Skip Record Function 


WAIT 
4 
number of records to skip (1 to 32767) 
number of records not skipped 
(0 unless EOF or physical EOT is encountered) 


Function code 
Parameter 
Value returned 


The Skip Record function advances the magtape down the tape. The tape 
continues to advance until either the desired number of records is 
skipped (in which case the value returned by the function is 0) or an 
EOF record is encountered (in which case the value returned is the 
specified number of records to skip minus the number actually 
skipped).(1) For example, to skip from the current tape position to 
just past the next EOF, use the following function: 


200 I% = MAGTAPE (4%,32767%,2%) 
This assumes there are fewer than 32767 records before the next EOF. 


In Section 2.8.7, a more complex example using the MAGTAPE function 
shows how to skip an entire file regardless of the number of records. 
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2.8.5 Backspace Function 


WAIT 
Function code = 5 
Parameter = number of records to backspace (1 to 32767) 
Value returned = number of records not backspaced (0 unless EOF 


or beginning-of-tape is encountered) 


The Backspace function is similar to the Skip function, except that 
tape motion is in the opposite direction. The beginning-of-tape (BOT 
or Load Point) as well as EOF records can cause premature termination 
of the Backspace operation (in which case the value returned is the 
specified number of records to backspace minus the number actually 
backspaced).(2) The BOT is neither skipped nor counted as a skipped 
record. For example: 


200 I% = MAGTAPE (5%,1%,2%) 


backspaces one record on the magtape opened on internal channel 2, 
unless the tape was already at BOT. 


2.8.6 Set Density And Parity Function 


IMMEDIATE 
Function code = 6 (Insignificant) 
Parameter = E+D*4+P 
Value returned = 0 
where: 
E = Phase Encoded 
256 = 1600 BPI, phase encoded mode 
0 = values of D and P (see below) 
D = Density 
0 = 200 BPI (7-track only) 
1 = 556 BPI (7-track only) 
2 = 800 BPI (7-track only) 
3 = 800 BPI, dump mode 
P = Parity 
0 = odd 
1 = even 


(1)The system counts the EOF record as a record skipped. 


(2)The system counts the EOF record as a record actually backspaced. 
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Magtape drives are set to the system default density/parity when first 
assigned (with an ASSIGN statement) or when first opened. This 
function changes the density and/or parity of a magtape drive 
according to the value given as the parameter. The function 
interprets the parameter exactly as MODE value (see Section 2.7). For 
example, 


10 OPEN "MTO:" AS FILE 2% 
20 IS=MAGTAPE (6%, 2%*4%+1%, 2%) 


changes the density and parity of the 7-track magtape drive open on 
channel 2 to 800 BPI, even parity, non-dump mode. The density and 
parity specified in the parameter is in effect until channel 2 is 
closed. The system sets 1% to 0 to indicate successful completion. 


By adding 8192% to the parameter value (making it 8192%+2%*4%+1%, in 
the above example), the new density/parity setting is in effect even 
after the associated channel has been closed. A subsequent OPEN 
statement, associating any channel number with magtape unit 0, opens 
it with that new density/parity setting automatically. Only a 
DEASSIGN statement to a previously assigned unit or another parameter 
specified in this function can revert the density/parity setting for 
the magtape unit back to the system default value. 


The sample routine shown below in immediate mode sets magtape unit 2 
to 800 BPI, dump mode, odd parity, using DOS labels. Once channel 3 
is closed, in this example, the new density/parity setting is now in 
effect and remains in effect until a DEASSIGN statement is executed on 
Magtape unit 2. 

ASSIGN MT2:.DOS 

OPEN "MT2:" AS FILE 33% 

I$=MAGTAPE (6%, 8192%+3%*4%, 3%) 


CLOSE 3% 


2.8.7 Tape Status Function 


IMMEDIATE 
Function code = 7 (Insignificant) 
Parameter = unused 
Value returned = status 


The Tape Status function returns the status of the specified magtape 
as a 16-bit integer, with certain bits set, depending on the current 
status. The format is shown in Table 2-1. The example shown below 
obtains the status of the magtape opened on internal channel number 2: 


200 I% = MAGTAPE(7%,0%,2%) 
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Table 2-1 
Magtape Status Word 


Is < 0% Last command caused an error 
(I% AND 24576%) /8192% Density: 200 BPI 
556 BPI 
800 BPI 
800 BPI, dump mode 


0 
1 
2 
3 


4096%) = 0% 9-track tape 
4096%) <> 0% 7-track tape 


2048%) = 08% Odd parity 
2048%) <> 0% Even parity 


1024%) <> 0% Magtape is physically write locked 
512%) <> 08% Tape is beyond end-of-tape marker 


256%) <> 0% Tape is a beginning-of-tape (Load 
Point) 


128%) <> 0% Last command detected an EOF 


64%) <> 0% The last command was READ and_ the 
record read was longer than the I/0 
buffer size (i.e., part of the 
record was lost). 


32%) <> 0% Unit is non-selectable (OFF-LINE) 
16% <> 0% Unit is TU16 


8%) <> 0% 1600 BPI, phase encoded mode (for 
TU16) 


7%) Indicates last command issued: 


OFF-LINE 

READ 

WRITE 

WRITE EOF 

REWIND 

SKIP RECORD 
BACKSPACE RECORD 
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When the value of I% returned is 17,409 decimal (or 42001 octal), the 
magtape is 800 BPI, 9-track, odd parity, write protected, and the last 
command issued was READ. This can be determined by testing the value 
of I%, bit by bit, against Table 12-1, as follows: 


It 


17,409 (decimal) 


= 4 2 0 0 1 (octal) 


100 010 000 000 001 (binary) 
The test for density uses bits 14 and 13: (1% AND 24576%)/8192% 
I% 100 010 000 000 001 
AND 17409% 110 000 000 000 000 
Result 100 000 000 000 000 


Dividing the result of (I% AND 24576%) (in this case, that result is 
16384%) by 8192%, the quotient can equal 0, 1, 2, or 3. In this case, 
16384/8192 = 2, indicating that the tape density is 800 BPI. 


The results of (1% AND 4096%) and (1% AND 2048%) are both zero, 
indicating a 9-track tape with odd parity. (1% AND 1024%) results in 
a non-zero number in this case, so the magtape is physically write 
locked. 


Bits 9 through 3 of I% in this example are all zero, but (1% AND 7%) 
results in 1%, indicating bit 0 is set and the last command issued was 
READ. 


Another magtape status function can advance to the next EOF (i.e., 
skip over the current file). The Skip Record function can do this 
unless the file is longer than 32,767 records -- in which case several 
skip record functions must be executed -- or an EOT is detected within 
a file. The following statements execute a Skip Record function until 
the next EOF is encountered. 


200 1% = MAGTAPE (4%, 32767%,2%): 
IF (MAGTAPE(7%,0%,2%) AND 128%) = 0% THEN 200 


2.8.8 Return File Characteristics Function 


IMMEDIATE 
8 (Insignificant) 
unused 
file characteristics 


Function code 
Parameter 
Value returned 


This function returns the status of the specified file structured 
magtape as a 16-bit integer, with certain bits set depending on the 
current file characteristics. The format is shown in Table 2-2. 
Non-zero integers are returned for DOS files; zero is returned for 
ANSI files. 


For example, to obtain the characteristics of a file on a magtape 
opened on channel 2: 


400 I% = MAGTAPE (8%,0%,2%) 
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When the value of I% returned is 16,464 decimal (40120 octal), the 
Magtape file is in ANSI format F, carriage control is embedded 'M', 
and the record length is 80 bytes. This can be determined by testing 


the value of I%, bit by bit, against Table 2-2, as follows: 


aiucl Nit, SQSALH Se 1AV45 £274, SS 10440WS. 


I 16,464 (decimal) 


0 4 0 1 2 0 (octal) 


0 100 000 001 010 000 (binary) 


The test for ANSI format type is (SWAP%(I%) AND 192%)/64%, where 192% 
= 128% + 64%. 


SWAP%(I%) 0 101 000 001 000 000 
AND 192% 11 000 000 
Result 1 000 000 
Dividing the result of SWAP%(I%) AND 192% (in this case, that result 
is 64%) by 64%, the quotient equals 64%/64% = 1, indicating that the 
Magtape is under ANSI format F. 


The result of (I% AND 12288%)/4096% is 0 in this example, indicating 
that the carriage control is embedded 'M'. 


Finally, the result of (I% AND 4095%) yields 80 in this case, so the 
record length is 80 bytes. 
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Table 2-2 
Magtape File Characteristics Word 


Meaning 


(SWAP%(I%)AND 192%) /64% | ANSI format: U (undefined) 
F (fixed length) 
D (variable length) 


S (spanned (1) ) 


0 
1 
2 
3 


(I% AND 12288%) /4096% Format U operation: 
0 (default) 
Format D, S and F operation: 
0 (carriage control embedded 'M') 
1 (FORTRAN carriage control '‘'A') 
2 (implied LF/CR before record' ') 


I% AND 4095$% Format U operation: 

0 = (default) 

Format F operation: 
Record length 

Format D operation: 
Maximum record length 

Format S operation: 
unused 


2.8.9 Rewind On CLOSE Function 


IMMEDIATE 
Function code = 9 (Insignificant) 
Parameter = unused 
Value returned = 0 


The Rewind on CLOSE function causes the selected magtape to be rewound when 
the CLOSE statement is executed. For example: 


I% = MAGTAPE (9%,0%, 2%) 


rewinds the magtape open on internal channel 2 when CLOSE is executed from 
a program or when CLOSE is executed in immediate mode. 


The Rewind on CLOSE function must be used after the OPEN statement and 
before the CLOSE statement. This function overrides all MODE 
specifications which, in the OPEN statement, instruct the system not to 
rewind on closing the file. Once the Rewind on CLOSE function is executed, 
it cannot be cancelled. 
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2.9 MAGTAPE ERROR HANDLING 


It is important to consider details of the system's handling of magtape 
error conditions. These are: parity error, record length error, off-line 
(not ready) error and write lock error. 


2.9.1 PARITY (Bad Tape) ERROR 


If an error is detected on a read attempt, the system attempts to re-read 
the record up to 15 times. If the error condition persists, a USER DATA 
ERROR ON DEVICE error occurs. In this case, the read has been completed, 
but the data in the I/O buffer cannot be considered correct. On an output 
operation, if the first attempt to write a record fails, the system 
attempts to rewrite the record up to 15 times using write with Extended 
Interrecord Gap to space past a possible bad spot on the tape. If the 
error condition persists, a USER DATA ERROR ON DEVICE error occurs. In 
both cases, the tape is positioned just past the record on which the error 
occurred. 


2.9.2 RECORD LENGTH ERROR 


This error can occur only during a read operation when the record on _ the 
Magtape is longer than the I/O buffer size, as determined by the OPEN 
statement. The extra bytes in the record are not read into memory but are 
checked for possible parity errors. If a parity error occurs, an error 
message is returned to the user program, and bit 6 of the magtape status 
word is set. Therefore, if a program is reading records of unknown length 
from magtape, it is necessary to check for possible record length errors 
after every read operation. This can be done as follows: 


200 PRINT "RECORD TOO LONG" IF MAGTAPE (7%,0%,2%) AND 64% 
Note that in the above example if bit 6 is set in the magtape status word 
the IF condition tests as TRUE. The error, MAGTAPE RECORD LENGTH ERROR 


(ERR = 40), occurs when the tape block is too long, in file-structured or 
non-file structured magtape. 
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2.9.3 OFF-LINE ERROR 


The status of the magtape unit is determined by testing bit 5 of the 
returned value of the magtape status function shown in Table 2-2. If bit 5 
is set, the magtape unit is off-line. A MAGTAPE SELECT ERROR (ERR = 39) 
occurs if an attempt to access an off-line drive is made. 


2.9.4 WRITE LOCK ERROR 


Attempting any write operation on a magtape that is physically write locked 
(i.e., a tape that does not have the write enable ring inserted) results in 
a "DEVICE HUNG OR WRITE LOCKED" error. 


2.10 THE KILL AND NAME AS STATEMENTS 


The KILL and NAME AS statements described in the BASIC-PLUS Language Manual 
are applicable only to disk and DECtape files; they cannot be used with 


magtape files. 


CHAPTER 3 


LINE PRINTER 


3.1 SPECIAL CHARACTER HANDLING 


Certain characters have special significance on line printer output. 
Table 3-1 summarizes LP1l and LS11l operation under RSTS/E for each of 
these special characters. 


Table 3-1 
LS11 and LP1ll Commands 


LS11 Function LP1ll Function 


CHRS (7) 


BELL 
(A 2-second audible tone) 


Ignored by driver 


CHRS (9) TAB - Horizontal Tab 
1. Spaces over to next 
tab position (columns 


1, 9, 17, 25, etc.) 


TAB - Horizontal Tab 

l. Spaces over to next 
tab position (columns 
1, 9, 17, 25, etc.) 


CHRS (10) ~ Line Feed 
1. Print line 
2. Carriage return 


3. Advances paper one line 


- Paper Feed 
l. Print line 
2. Carriage return 

3. Advances paper one line 


CHRS (11) VT - Vertical Tab 
l. Advances paper to the next 


hole position in Channel 5 


VT - Vertical Tab 
l. Ignored by driver 
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Table 3-1 (Cont.) 
LS11 and LP11 Commands 


Character LS11 Function LP1l Function 


FF - Form Feed 

1. Print line 

2. Carriage return 

3. Advances paper to the 
third line of the next 
form (hardware top of 

form, see Section 3.2) 


CHRS (12) - Form Feed 

1. Print line 

2. Carriage return 

3. Advances paper to the next 
hole position in Channel 7 


(see Section 3.2) 


CHRS$ (13) 


R - Carriage Return 


Cc CR - Carriage Return 
1. Print line 

2 

3 


1. Print line 
2. Carriage return 


3. No line feed (may be 
used for overprint) 


Carriage return 
No line feed (may be used 
for overprint) 


CHR$ (14) ELONG - Elongated Character 
1. Doubles the horizontal 


printing axis 


ELONG - Elongated Character 
1. Ignored by driver 


CHR$ (17) SEL - Select 


1. Ignored by driver 


SEL - Select 
1. Allows the software to put 
the printer on-line 


CHRS (19) DSEL - Deselect 


1. Ignored by driver 


DSEL - Deselect 
1. Allows the software to put 
the printer off-line 


CHRS (96) 
to 
CHRS$ (126) 


1. Lower case printing 
characters, converted 
to upper case except on 
an upper case/lower 
case printer. 


1. Lower case printing 
characters, converted 
to upper case 


CHRS$ (127) | DEL - Delete 


1. Ignored by driver 


DEL - Delete 
1. Ignored by driver 


3.2 SPECIAL OPERATIONS 


The MODE specification in the OPEN statement allows the user to 
control line printer operations. For example: 


OPEN "LP:" AS FILE F%, MODE M% 
The system associates line printer unit 0 with the channel designated 
by F%. The value of M% in the MODE specification determines the 


actions the system performs at the line printer. The following MODE 
values generate the action described at the line printer unit. 
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MODE Value Action 

1 to 127 Sets form length in number of lines per page for 
software formatting (512%) and/or automatic page 
skip (2048%). This is the LPFORM option. 

128 Change the character 0 to the character O. 

256 Truncate lines which are longer than the unit was 


configured for. This action is done in place of 
printing the remainder of the line on the next 
physical line on the page. 


512 Enable software formatting. Forms control 
characters are >128. 


1024 Translate lower case characters to upper case 
characters. Applies only to upper and lower case 
line printers. 


2048 Skip six lines (i.e., over perforation line) at 
the bottom of each form. 


4096 Moves paper to top of hardware form. CHR$ (12%). 
(See discussion, below.) 


The MODE value 512% allows a program to control non-standard length 
forms in the line printer(1). To accomplish this action, the program 
must include a MODE value between 1 and 127 to indicate the number of 
lines per page on the printer. For example, 


100 OPEN "LPO:" AS FILE 1%, MODE 542% 


The statement sets the form length to 30 lines per page (512%+30, or 
542%). If neither the 512% nor the value for form length is given, 
the system uses 66 lines per page as the form length. Lines are 
numbered from 1 to the length specified. Thus, in this example, lines 
are numbered from 1 to 30. 


As a result of enabling the software formatting with MODE 512%, 
certain special characters that the program sends to the line printer 
determine the number of the line on which the system prints data. The 
system skips to this line by sending the proper number of LINE FEED 
characters to the printer. It determines the line on which to. print 
by subtracting 127 from the decimal value of the special character the 
program sends to the printer. For example, 


PRINT #1, CHRS$ (147%); 


This statement causes the system to evaluate the difference between 
147 and 127. If the difference is greater than the page length 


(1)The hardware option on the LP1l High Speed Printer to automatically skip 
over perforations must be disabled for this option to execute properly. 


LINE PRINTER 


specified in the MODE value or more than 66 when no page length is 
specified, the system ignores it. If the difference is less than the 
page length in effect but greater than the current line number, the 
printer skips to that line number on the current page. If the 
difference is less than or equal to the number of the current line, 
the system skips the printer to the appropriate line on the next page. 


NOTE 


To enable the program to properly 
perform software formatting of print 
lines using special characters, the user 
must load the paper in the line printer 
with the top of form at the arrows and 
with the tractors set at their top of 
form position. See the RSTS-1ll System 
User's Guide for line printer operating 
procedures. 


The system treats characters whose values lie between 0 and 127 as the 
standard ASCII equivalents as shown in Appendix D. In addition, a LF 
character sent to the printer advances the form to the first print 
position of the next line (i.e., LF implies CR). If a form length 
other than 66 is specified but MODE 4096% is not specified, a CHR$ (12) 
in the data passed by the program to the line printer translates to a 
sufficient number of line feed characters to move the page to the top 
of (software) form. If the form length is 66 or zero (the default 
value which results in 66) or MODE 4096% is specified, CHR$(12) 
remains untranslated and positions the printer paper at the top of the 
hardware form. 


A value of 128 in the MODE specification causes the system to print 
all O characters as O characters. This feature is valuable in 
commercial applications where there can be no _ possibility for 
confusion. For example, 


10 OPEN "LPO:" AS FILE 1%, MODE 706% 


The statement indicates software formatting (512%) and translation of 
0 to O (128%) is to be performed on line printer unit 0 with a form 
length of 66. That is, MODE 706% is equivalent to MODE 512%+128%+66%. 


To truncate lines greater than the width of the line printer, the user 
program includes 256% in the MODE value. For example, 


10 OPEN "LPO:" AS FILE 1%, MODE 962% 
The statement implements the MODE value of 66%, 128%, 256% and 512%, 
on line printer unit 0 and discards excess characters from each line 
printed (MODE 256%). Without 256% in MODE, the system prints excess 
characters on a second physical line. 


To translate lower case characters to upper case characters, the user 
program includes 1024 in MODE. For example, 


10 OPEN "LPO:" AS FILE 1%, MODE 1986% 
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This statement implements the MODE values 66%, 128%, 256% and 512% 
and, in addition, causes the system to translate all characters with 
representations between CHR$(96) and CHR$(122) to their equivalents 
between CHRS(6%) and CHRS(90). This feature is always set for an 
upper case only printer. 


To skip six lines at the bottom of each form, the user program 
includes 2048 in MODE. For example, 


10 OPEN "LPO:" AS FILE 1%, MODE 4034% 


The statement implements the MODE values 66%, 128%, 256%, 512%, 1024%, 
and also skips six lines when the system advances the page to top of 
form. With this value in effect, the system does not print on _ the 
last six lines of each form. This feature is useful when generating 
continuous listings to be placed in horizontal binders. If the user 
loads the line printer as such that the top of form is the third 
physical line on the page, the system leaves three blank lines at the 
beginning of the next page. When the listings are subsequently placed 
in binders, printed material is located three lines from the 
perforations of the page to facilitate easy access. 


The system handles the actual transfer of data from user storage to 
the line printer by means of an intermediate storage called small 
buffers. This allows the faster computational process to continue 
unhindered by the slower output action at the line printer. Thus, for 
each output request in a user program, the system transfers’ the 
related program data from program storage to small buffers. At the 
same time, at its own speed, the line printer software extracts the 
data from the intermediate small buffers and performs the output to 
the device. 


An error condition at the line printer causes the system to interrupt 
the transfer of data both from the buffers to the device and from the 
program to the buffers. Since any number of indeterminate events such 
as a ribbon jam or a paper tear can cause an error condition, the 
system retains the unprinted data in the buffers until either the 
error is cleared (the unit becomes ready again) and the user program 
executes a CLOSE operation. 


The system checks the status of the line printer every ten seconds, 
and, upon detecting the ready condition again, continues output from 
the small buffers without loss of data. If the user program closes 
the line printer while the error is still pending, the system returns 
the small buffers to the pool without printing their contents. The 
data transferred from the program but not yet printed is lost. 


If the user program disregards the error condition and continues 
processing, the system does not transfer more data to additional small 
buffers. No output occurs at the line printer while the error 
condition remains in effect. 
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To prevent loss of data, a user program must properly detect a line 
printer error condition and execute efficient error handling. The 
system indicates the line printer error by generating the DEVICE HUNG 
OR WRITE LOCKED error (ERR = 14). The first time this error is 
returned after an output request (e.g., PUT), the data is fully 
buffered by the monitor. No data is lost, but the buffered data 


cannot be sent to the printer due to the error 
seconds the monitor checks the printer's 


printing when the error condition is rectified. 


monitor free space, subsequent output 
immediately without any further data buffering 
the error condition persists. When the output 
error, the printer error condition is cleared. 


The sample program shown below demonstrates code 


following actions: 


condition. Every 10 
status. It will resume 

To prevent filling up 
reguests are returned 
and with ERR=14 while 
request returns without 


which performs the 


a. opens the line printer, inputs a line from the disk file, and 
performs output to the line printer, and 
b. performs efficient error handling as described above. 
10 ! HOUSEKEEPING 
20 OPEN "DATA.DAT" FOR INPUT AS FILE 1 
30 OPEN "LPO:" AS FILE 2, RECORD SIZE BUFSIZ(1$%) 
40 FIELD #1, BUFSIZ(1%) AS IS 
50 FIELD #2, BUFSIZ(2%) AS O$ 
60 E% = 08% 
70 ON ERROR GOTO 200 
100 ! DATA MOVING LOOP 
110 GET #1 
120 C% = RECOUNT 
130 LSET O$ = I$ 
140 PUT #2, COUNT C% 
150 E% = O8% 
160 GOTO 100 
200 ! ERROR HANDLING 
210 IF ERR=11 AND ERL=110 THEN RESUME 400 
220 IF ERR=14 AND ERL=140 THEN RESUME 300 
230 ON ERROR GOTO 0 
300 ! PRINTER ERRORS 
310 IF E% THEN 350 
320 ! FIRST TIME ERRORS (DATA WAS BUFFERED) 
330 E% = ~-1% 
340 GOTO 100 
350 ! SUBSEQUENT ERRORS (DATA NOT BUFFERED) 
360 PRINT "?LINE PRINTER ERROR?" 
370 SLEEP 108% 
380 GOTO 140 
400 ! DONE 
410 CLOSE 1, 2 
999 END 


CHAPTER 4 


TERMINALS 


Several features are available to facilitate processing on keyboard devices 
using Record I/O statements. 


4.1 CONDITIONAL INPUT FROM A TERMINAL 


Sometimes a program must execute an input request from a terminal without 
waiting for data to be available. (The terminal may be opened on a 
specific I/O channel or may be one of many terminals opened on one _ I/O 
channel - see Section 4.3.) Normally, the system stalls the program 
executing an input request until data is available in the keyboard input 
buffer (i.e, a line terminator is typed at the keyboard). To avoid 
stalling, the program can execute a statement similar to the following: 


GET #1%, RECORD 81923% 


If data is available from the terminal open on channel 1, the system makes 
it accessible to the program in the channel 1 buffer. The number of bytes 


read from the terminal input buffer is given by the RECOUNT variable. If 
no data is available, the system generates the USER DATA ERROR ON DEVICE 
error (ERR = 13). In both cases, the system reports the results 
immediately. 


4.2 BINARY DATA OUTPUT AND INPUT 
To perform binary data output to a terminal, either opened on its own I/O 
channel or opened as one of many terminals on one I/O channel, execute a 
statement of the following form: 

PUT #N%, RECORD 4096%, COUNT M% 


or 


PUT #N%, RECORD 1%, COUNT M% 


TERMINALS 


The statement transfers the number of bytes specified by M% to the output 
buffer of the terminal open on channel N%. No special form of the output 
statement is required. As a result of specifying RECORD 4096% or RECORD 13% 
in the PUT statement, all output formatting on the terminal is disabled. 


A user program can obtain binary input from a keyboard by executing the 
OPEN statement with a MODE 1% option. For example, 


10 OPEN "KB6:" AS FILE N%, MODE 1% 


The statement associates channel N% with keyboard number 6 in binary input 
mode. As a result, characters received are not echoed by the system and 
are not altered in any way. In this manner, a program can read binary data 
from a terminal paper tape reader, from the terminal itself, or from any 
device connected to the system through a keyboard interface. 


To initiate a transfer of data, use the GET statement. For example, 
GET #N% 


The system transfers some number of characters from the keyboard open on 
channel N% to the buffer for that channel. If no data is available, the 
system stalls the operation until data is received from the keyboard. When 
data is received, the program is made runnable and the data is available in 
the buffer. The BASIC-PLUS program must execute GET statements frequently 
enough to avoid losing data from the transmitting device. 


The number of characters received is always at least one and never more 
than the channel buffer size. The default buffer size for keyboards is 128 


characters. The user can override the default buffer size by the 
RECORDSIZE option in the OPEN statement. The RECOUNT variable contains the 
actual number of characters received. 


Since the system accepts and does not alter any characters received from a 
terminal open for binary input, typing “C on such a terminal has no effect. 
For this reason, the system disables binary input mode under the following 
conditions. 


a. The period for a WAIT statement expires 


b. Executing a statement on channel zero when the user's keyboard is 
open for binary input 
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c. Executing an OPEN statement in normal mode on the device but on a 
different channel 


d. Executing a CLOSE statement on any channel associated with a 
keyboard open for binary input 


For condition a, the system disables binary input mode if time for a WAIT 
is exhausted. For example, 


10 WAIT 10% 
20 GET #1% 


If the system does not detect data within 10 seconds on channel 1, which is 
open for binary input, it disables binary mode in addition to generating 
the KEYBOARD WAIT EXHAUSTED error (ERR = 15). The keyboard remains open 
for normal ASCII data transfers. 


For condition b, the system disables binary input mode when the program 
executes a statement on channel 0 and the user's keyboard is open for 
binary input on a non-zero channel. For example, 


10 OPEN "KB:" AS FILE 1%, MODE 1% 
20 GET #1% 


40 PRINT "MESSAGE"; 


The statement at line 10 opens the user's keyboard for binary input on a 
non-zero channel (channel 1). The statement at line 20 performs binary 
input from the keyboard. At line 40, however, the system executes a PRINT 
statement on the user's keyboard (channel 0) which disables binary input 
mode. The user's terminal remains open on channel 1 for normal ASCII data 
transfers, 


For condition c, the system disables binary input on a channel if the 
program executes a normal OPEN on the same device but on a different 
channel. For example, 


10 OPEN "KB6:" AS FILE 1%, MODE 1% 


100 OPEN "KB6:" AS FILE 2% 


AS a result of statement 100, the system disables binary input on keyboard 
6. If statement 100 contained MODE 13%, the system would open keyboard 6 
for binary input on channel 2. Keyboard 6 would therefore be open for 
binary input on both channels. 


For condition d, the system disables binary input if the program executes a 
CLOSE statement on any channel associated with a keyboard open for binary 
input. For example, 


10 OPEN "KB6:" AS FILE 1%, MODE 13 
20 OPEN "KB6:" AS FILE 2%, MODE 13 


. 


100 CLOSE 2% 
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At line 100, the CLOSE statement disassociates channel 2 from keyboard 6 
but also disables binary input on channel 1. Keyboard 6 remains open in 
normal mode on channel 1. 


The recommended method of using binary input mode is to open a device other 
than the user's terminal for binary input on any non-zero channel. The 
program interacts normally with the user's terminal by executing standard 
INPUT and PRINT statements and gathers data from the binary device on the 
non-zero channel by executing GET statements. 


Since binary input disables all special character handling, the system 
cannot detect an end of file on a terminal transmitting binary data. 
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4.3 MULTIPLE TERMINAL SERVICE ON ONE I/O CHANNEL 


The multiple terminal feature allows one program to interact with several 
terminals rather than merely having each terminal open for input or output. 
This feature is useful in applications such as order entry, inventory 
control, and query-response where the same function is performed on several 
terminals but a separate job for each terminal is undesirable or 
inefficient. 


To implement control of several terminals, the BASIC-PLUS program must 
first establish a master terminal by opening a keyboard on a non-zero 
channel. Two forms of the OPEN statement are possible. For example, 


10 OPEN "KB:" AS FILE N$ 
or 
10 OPEN "KB4:" AS FILE N% 


The first form associates channel N% with the current keyboard and defines 
it as the master’ terminal. The second form associates channel N% with 
keyboard number 4 and defines it as the master terminal. 


The program exercises control of additional, or slave, terminals, through 
special forms of the Record I/O GET and PUT statements. The terminals must 
be reserved to the job but must not be open in the program. The user can 
establish the terminals as slave terminals with the ASSIGN immediate mode 
command before he runs the program. Alternatively, the program can assign 
these terminals by executing the number 10 SYS system function call to FIP. 
The program can control any number of these additional terminals up to. the 
maximum number of terminals on the system. 


To perform input and output operations, the program uses GET and put 
statements in a special manner. The RECORD option specifies a particular 
action and keyboard number. 


A PUT statement of the following form performs Output to a keyboard, either 
Master or slave. 
10 PUT #13 


v ros 


The variable K% in the RECORD option is the unit number of the keyboard to 
which output is directed. As a result, the number of characters specified 
by N% in the COUNT option is transferred from the buffer on channel 1 to 
the designated keyboard. The only special error which can occur is NOTA 
VALID DEVICE (ERR = 6), indicating that the terminal addressed is neither 
the master keyboard nor a slave keyboard reserved to the program. Other 
possible errors such as I/O CHANNEL NOT OPEN (ERR = 9) work in the standard 
fashion. 
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A GET statement of the following form performs input from a keyboard, 
either master or slave. 


10 GET #1%, RECORD 32767%+1%+K% 


The variable K% in the RECORD option is the unit designator (keyboard 
number) of the terminal from which input is requested. The GET statement 
transfers the data from the terminal input buffer to the buffer for the 
designated channel. The first character in the buffer contains the number 
of the keyboard from which the input came. The total number of characters 
transferred, including the keyboard number, is given by the RECOUNT 
variable. The program accesses the data by use of the standard FIELD 
statement. Since the first character of the 1/0 buffer is the keyboard 
number, the length of the data input is given by RECOUNT-1%. If no input 
is available from the designated terminal, the USER DATA ERROR ON DEVICE 
error (ERR = 13) results. Since this error is recoverable, the program can 
execute an appropriate ON ERROR GOTO routine. 


The following form of the GET statement requests input from any one of the 
multiple terminals. 


10 GET #1%, RECORD 32767%+1%+16384%+5% 


If input is pending from any terminal, the contents of that terminal's 
buffer are transferred to the buffer for the designated channel. The first 
character in the buffer is the keyboard number of the terminal from which 
input came. As described above for input from a specific keyboard, the 
FIELD statement can access the sending keyboard number and the data sent. 
The variable S% can have the following values: 


Value Meaning 
S%=0% GET statement waits until input is available from any 
one of the terminals. The system waits indefinitely if 
no input is pending. When input is available, the 


system transfers the data and the program accesses the 
data as described above. A USER DATA ERROR ON DEVICE 
error (ERR =13) may occur due to a race condition with 
CTRL/C. No data is lost; simply re-issuing the GET 
statement continues operation. 


1$<S%<255% GET statement waits up to S% seconds for input from any 
terminal. If no input is available from any terminal 
in §% seconds, the USER DATA ERROR ON DEVICE error 
(ERR = 13) occurs. 


S%=4096% Binary data (see Section 4.2) 
$%=8192% If no input is pending from any of the terminals, the 


USER DATA ERROR ON DEVICE error (ERR = 13) occurs 
immediately (see Section 4.1). 
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A CTRL/C combination typed at any one of the slave terminals passes a 
CHR$(3) character to the program but does not terminate the program. The 
RECOUNT variable contains the value 2% representing the keyboard number and 
the CTRL/C character. The program can process the CTRL/C character as a 
special character. If CTRL/C is typed at the master terminal, the system 
terminates the program in the standard fashion. 


A CTRL/Z combination typed at a master or at a slave terminal causes the 
END OF FILE ON DEVICE error (ERR = 11) to occur. The unit number of the 
keyboard causing the error is returned as the first character in the buffer 
on the channel. The value of the RECOUNT variable is meaningless. 


When the value 4096% is also included in the RECORD option, binary data can 
be output using this multiple terminal service. For example, 


100 PUT #N%, RECORD 32767%+1%+4096%+K%, COUNT M3 


is used to output the number of bytes of binary data specified by M% to the 
keyboard whose unit number is the variable K%. 
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4.4 ESCAPE SEQUENCES 


4.4.1 Output Escape Sequences 


When sending an escape sequence to a terminal, use the value CHR$(155) (233 
octal) for the escape character rather than CHR$(27) (033 octal). The 
system translates CHR$(27) to CHRS$(36) (044 octal) which is the dollar sign 
($) character. The system translates neither the CHR$(155) character nor 
the character following it. This process allows the terminal to interpret 
the escape sequence transmitted. 


4.4.2 Input Escape Sequences 


There are two I/O operating modes which are set by the MTTYSET system 
program: NO ESC SEQ mode and ESC SEQ mode. In NO ESC SEQ mode, an 
incoming ESC character -- CHR$(27) (033 octal) -- acts as a delimiter. The 
system echoes a _  CHR$(36) (044 octal), which is the dollar sign ($) 
character. 


In ESC SEQ mode, however, an incoming CHR$(27) merely sets a flag 
indicating that the next input character is special; no character is 


echoed when CHR$(27) is input in ESC SEQ mode. The next character input 
after ESC acts as a delimiter, but does not echo. This second character 
clears the previously set flag. The system then reverses the order of the 
last two characters and translates the CHR$(27) to CHR$(155) (233 octal). 
For example, in ESC SEQ mode, if the two incoming characters are: 

ESC P (CHRS$ (27) ,CHRS (80) ) 
the system transposes this to: 

P ESC (CHR$ (80) ,CHRS (155) ) 
In this way, the character input immediately after ESC is retained and can 


be used or tested by the user program. Some terminals (see following 
sections) and other devices respond to escape sequences. 
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4.5 VT05 CURSOR CONTROL AND SPECIAL CHARACTERS 


The VT05 alphanumeric display terminal recognizes certain control 
Characters that are not used on other terminals. These are summarized in 


matt 


Table 4-1. 


Table 4-1 
VT05 Special Display Characters 


Character String 


CHRS (8) BACKSPACE (move cursor left one character). 
CHRS (11) CURSOR DOWN (one line, same position). 
CHRS (14) Direct cursor control 


The next two characters give x- and y-coordinates of 
the new cursor position on the 20-line by 72-character 
VTO5 screen. 


The characters following CHRS (14) are, first, 


CHRS$ (32+Y) and second, CHRS (32+X). Y is the 
y-coordinate (0 to 19), and xX is the x-coordinate (0 to 
71). 

CHRS (24) CURSOR RIGHT (one character) 

CHRS (26) CURSOR UP (one line, same position). 

CHRS (29) HOME UP (move cursor to upper left hand corner of 
display screen). 

CHRS (30) ERASE EOL (erase to end of line). 

CHRS (31) ERASE EOS (erase to end of screen). 


In the statements shown below, X% is the column number (X-axis) and Y% is 
the line number (Y-axis). The upper left-hand corner is defined by the 
coordinates, (0,0). The following statement shows how direct cursor 
control (CHR$(14)) is used to position the cursor to (X%,YS): 

PRINT #N%, CHRS (14%); CHRS (32%+Y$%); CHRS (32%+X$%) >; 
The semicolons prevent automatic carriage return. 


The statement shown below combines CHR$(14) and CHRS$ (32). The cursor is 
positioned to (X%,Y%) and the screen is cleared. 


PRINT #N%, CHRS$(14%); CHRS(32$+Y%); CHRS (32%$+X%); CHR$ (31%); 
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4.6 VT50 CURSOR CONTROL AND SPECIAL CHARACTERS 


The Full Duplex/Full Duplex with Local Copy switch on the VT50 specifies 
the source of data received in Remote mode. When this switch is set to 
Full Duplex with Local Copy, data entered at the keyboard is transmitted to 
the terminal's receiver at the same time it is sent to the host computer. 
When the switch is set to Full Duplex, data transmitted from the keyboard 
goes to the computer only. This data may be echoed from the computer back 
to the terminal to give a visual image of the information transmitted. 


Because it permits an interactive relationship between the VT50 and the 
RSTS-11 system, Full Duplex is the most versatile of the two settings. For 
example, in Full Duplex the user can create unigue escape sequences; the 
receipt of ESC 1 (27 49) from the terminal can call one routine, ESC 2 
another, and so on. 
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The VT50 alphanumeric display terminal recognizes certain control 


characters that are not used on other terminals. These are summarized in 
Table 4-2. 


Table 4-2 
VT50 Special Display Characters 


Character String Character Meaning 
CHRS (8) BACKSPACE (move cursor left one character). 
CHRS (11) CURSOR DOWN (one line, same position). 
ESC (CHR$(155)) Followed By: 
CHRS (65) A CURSOR UP (one line, same position). 
CHRS (67) Cc CURSOR RIGHT (one character). 


CHRS (72) HOME UP (moves cursor to upper left hand 
corner of display screen). 


CHRS (74) ERASE EOS (erase to end of screen). 


CHRS (75) ERASE EOL (erase to end of line). 


CHRS (90) Requests the terminal to identify itself. 
The VT50 terminal will respond with ESC 
(27 47 65). The VT50 terminal with copier 
will respond with ESC (27 47 66). 


CHRS (91) Enables Hold Screen Mode. 


CHRS (92) Disables Hold Screen Mode. 
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4.7 PSEUDO KEYBOARD OPERATIONS 


A pseudo keyboard is a non-physical device which allows one job to control 
other jobs on the system. The number of pseudo keyboards on the system is 
determined at system generation time. The system denotes a pseudo keyboard 
by a device designator of PK and associates each pseudo keyboard unit to a 
keyboard unit number but not to a physical terminal device. 


The pseudo keyboard device has the characteristics of a terminal but has no 
physical device associated with it. As such, the pseudo keyboard has both 
input and output buffers to which user programs send input and from which 
they extract output. The output buffer of the pseudo keyboard is the input 
buffer for the keyboard unit and vice versa, yet no physical device is 
involved. 


The system transfers data to the pseudo device in full duplex mode. This 
mode means that strings transmitted by PUT statements are echoed by the 
system and available to the program by GET, INPUT or INPUT LINE statements. 
In addition, a CR character (CHR$(13)) sent to the PK buffer is returned 
from the KB buffer as a CR and LF character sequence. 


Use of a pseudo keyboard involves a controlling job and a_ controlled job. 
The controlling job initiates operations by performing output operations to 
the pseudo keyboard unit. It utilizes the pseudo keyboard to perform 
output to and receive input from the controlled job. The controlled job 
performs input/output operations on its own terminal, KB:. In effect, the 
controlled job does not know it is using a pseudo keyboard; only the 
controlling job is specifically using a pseudo keyboard. 


A controlling job accesses a pseudo keyboard unit by the OPEN statement 
with the device designator PKn:, where n is the unit number of the pseudo 
keyboard. For example, 


10 OPEN "PKO:" AS FILE 1% 


The OPEN statement associates pseudo keyboard unit 0 with internal channel 
number 1. If the device is assigned to or opened by another job, the 
ACCOUNT OR DEVICE IN USE error (ERR = 3) occurs. Otherwise the program can 
subsequently perform GET and PUT operations on the device by means of the 
buffer on channel 1. 


To obtain data output from the controlled program, the controlling program 
executes a Record I/O GET statement on the proper internal channel. For 
example, 


40 GET #1 


makes data from the pseudo keyboard available in the buffer for channel 1 
of the controlling program. If no input is available, an END OF FILE ON 
DEVICE error (ERR = 11) occurs. When no error occurs, the BASIC-PLUS 
variable RECOUNT contains the number of bytes in the buffer. The response 
from a GET statement is immediate. The controlling program is never 
stalled pending data availability. This means that when a GET is executed, 
the contents of the buffer is returned to the controlling job - whether it 
is a single message, multiple messages, or a message fragment. 


If the controlled job performs output faster than the controlling job can 
execute GET statements, the keyboard output buffer fills. Consequently, 
the controlled job enters an output wait state (TT) as if it were waiting 
for a real terminal. When the stall occurs, the system makes the 
controlling job eligible to run if it was in the SLEEP state so that it can 


TERMINALS 
execute GET statements and receive the output from the controlled job. 


To perform output to a pseudo keyboard, the controlling program executes a 
Record I/O PUT statement with a coded value in the RECORD option. For 
example, 


100 PUT #N%, RECORD R%, COUNT C$% 


The value N% is the internal channel number on which the PK device is open. 
The value C% is the number of bytes the program sends from the buffer to 
the PK device. The data sent from the buffer must be as one would type it 
at a keyboard. For example, if the controlling job sends a line which 
would normally be terminated by the RETURN key, the line sent must include 
only the CR character (CHR$(13)) and the value C% must reflect the CR 
character in the total number of bytes sent. The system automaticaly 
appends a LF character to a line terminated by a CR character. (The user 
normally does not type the LINE FEED key when he enters a line by typing 
the RETURN key.) 


The value R% in the RECORD option determines the actions the system 
performs for the specific PUT statement. R% is a decimal integer whose 
value the system interprets on a bit by bit basis. The system examines 
only the low order four bits numbered 0 through 3 counting from right to 
left in the 16-bit word. The system executes the PUT statement depending 
upon whether certain bits in the value R% are on or off. 


The flowchart of Figure 4-1 shows the actions the system performs by 
testing each bit in the RECORD R% option. For example, bit 0 (value =1) 


determines whether the system attempts to send data or performs tests 
before it sends data. Bit 1 (value = 2) is used to indicate whether the 
pseudo keyboard is waiting for a system command or is waiting for program 


input. Bit 2 (value = 4) actually sends data to the pseudo keyboard (if 
bit 0 is one) or simply returns control to the user program. Lastly, bit 3 
(value = 8) tells the system, upon encountering a lack of small buffers, 


either to return an error or to wait until small buffers are available. 


By alternately using PUT and GET statements, the controlling program starts 
a controlled job on the pseudo keyboard device. RECORD 1% sends data to 
the keyboard and can send LOGIN system program commands. A GET statement 
can retrieve output from the controlled job. For example, in response to 
the string "HELLO 10/10"+CHR$(13) sent to the pseudo keyboard, the system 
runs the LOGIN program. A subsequent GET statement can retrieve the echo 
and the PASSWORD: message printed by LOGIN. The controlling program can 
then send the proper password string and ensure that LOGIN accepted it. 


Once the controlled job is running, the controlling program can send system 
commands, program commands, and program responses to the PK device using 
various RECORD option values in the PUT statement. The program should send 
only one line at a time and retrieve each program or system response. 
Also, the controlling program must not send a line unless the PK device is 
waiting for keyboard input. The controlling program should always check 
the PK device status before attempting to send data. 


The RECORD 6% option (values 4 and 2) in a PUT statement can ensure that 
the controlled job is in editor mode (BASIC-PLUS command level). If it is 
waiting for KB input but is not in editor mode, the system generates error 
number 28. The user program must then force a CTRL/C combination to the 
controlled job. Otherwise, control is returned to the user program which 
can then transmit a system command. 


Now to execute a program under the controlled job, the controlling program 
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sends the RUN command with the program name to the PK device. To ensure 
that the controlled job is in the KB state awaiting keyboard input, the 
program first uses the RECORD 6% option in the PUT statement. If the 
controlled job is waiting for input, control is returned to the user 
program. Otherwise, the system generates error number 3. 


ERR=5 
(Jos IS NOT 
LOGGED IN) 


ERR =3 
(DEVICE IN 
USE) 


JOB 
IN EDITOR 
WAIT 

2 


EDITOR) 


SEND 
CHARACTERS 


RETURN 
CONTROL 
TO USER 


(NO ROOM FOR 
INPUT ON KB:) 


Figure 4-1 
PUT Statement Actions for PK Output 
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CHAPTER 5 


NON-FILE STRUCTURED DECTAPE 


In non-file structured processing of DECtapes, the user program can access 
specific physical blocks on the DECtape. To initiate non-file structured 
processing, the user program gives only a device designator in the OPEN 
statement. Of the three conventional forms of the OPEN statement, OPEN FOR 
INPUT, OPEN, and OPEN FOR OUTPUT, only two are valid. The following two 
statements, 


100 OPEN "DT1:" FOR INPUT AS FILE 1% 
and 
100 OPEN "DT1l:" AS FILE 13 


are equivalent because both reading and writing of physical blocks on the 
device are permitted. The following statement: 


100 OPEN "DT1l:" FOR OUTPUT AS FILE 3% 
is invalid since it attempts to create a file. 


After opening a DECtape device for non~file structured processing, GET and 
PUT statements can retrieve and write specific physical blocks on the 
device by means of the RECORD option. The record number specified is 
interpreted as a block number. When the RECORD option specifies a negative 
block number, the designated block is accessed backwards. (Block G cannot 
be accessed backwards.) For example: 


200 GET, #1% RECORD -4% 
reads block 4 of the file opened on channel 13 backwards. 


In writing non-file structured DECtape files, the user can specify how 
blocks should be accessed. But a file on a file structured DECtape is 
written on every fourth block (i.e., Block N, N+4, N+8, etc.) of the 
DECtape by the RSTS/E system. This procedure optimizes DECtape access 
time. When the system reaches the last block of the tape, it begins to 
write blocks backwards in intervals of four. It then repeats the entire 
process to fill in the available blocks on the DECtape. Therefore, to read 
a file structured DECtape in non-file structured mode, read every fourth 
block of the tape and use the RECORD -N$% option to read alternate blocks 
(in the order in which they were written) backwards. Repeat this procedure 
to read the remaining blocks on the DECtape. 


In file structured mode, since the blocks are not contiguous, the first 
word of each block of a file is a pointer to the next logical block of the 
file. These blocks are linked by these pointers. The DECtape format 


NON-FILE STRUCTURED DECTAPE 


diagram (Figure 5-1) shown on the next page is provided so that non-file 
structured DECtape access time can be minimized. 
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RESERVED FOR BOOTSTRAP 
LINKED FILES 


LINKED FILES 


FOR FILES 


FOR FILES 


FOR FILES 


FOR FILES 


FOR FILES 


BIT MAPS 


FOR FILES 


MFD BLOCK #1 


MFD BLOCK #2 
UFD BLOCK #1 


UFD BLOCK #2 
MASTER/PERMANENT BIT MAP 


LINKED FILES 
LINKED FILES 


MFD BLOCK #2 


RSTS does not read or check 
DECtape UIC's. 


When zeroing a DECtape RSTS 
enters a UIC of [1,1]. 


UFD_ BLOCKS 


RSTS ignores ~ LOCK Bits, USAGE COUNT, 
and END BLOCK entries in the UFD. 
RSTS checks the "TYPE" bit (bit 15) 
and will allow a "CONTIGUOUS" file 

to be OPENed. 


When creating a DECtape file, RSTS 
writes a protection code of 233g (for 
DOS-1ll' compatibility). But RSTS does 
not read or check DECtape protection 
codes. 


256 
words 


Le a56 


words 


256 
words 


Figure 
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FILE BIT 


{The 


The remaining 255 words are data. 
DECtape directory structure can catalog and map a maximum of 56 files. 


FILE BIT 


A DECtape has 576 blocks of 256 words each. 


The first word in every block of a linked file is a pointer to the next 
logical block of that file. 
of the next logical block; it is positive for forward tape motion and 
negative for backward tape motion.) 


pointer contains the physical block # 


Each File Bit Map has 36 
words (=576 bits) 


Each bit maps 1 block 


(36 WORDS) of the DECtape. (A set 


FILE 24 


FILE BIT 


FILE BIT 


bit means an allocated 
block; a clear bit means 
a free block.) 


(36 WORDS) FILE 25 


(36 WORDS) 


FILE BIT 


FILE BIT 


Ist 
2nd 
3rda 
4th 


word: 
word: 
word: 


{36 WORDS) FILE 27 


Each File Bit Map maps 


(36 WORDS) the entire DECtape. 


1flg (link to MFD block #2) 
4 (interleave factor) 
14g (pointer to lst Master Bit Map) 


194g (pointer to non-existant 2nd 
Master Bit Map) 


252 words unused 


lst word: § (link to non-existant MFD block #3) 


UIC 


POINTER TO UFD 
START BLOCK (12g) 


up to 63 4-word entries 
each with format shown OF WORDS PER 


UFD ENTRY (=9) 


lst word: 193g (link to next UFD block) or @ (end of 
chain) 


remainder unused. 


FILENAME (PART 1) RADS# 


FILENAME (PART 2) RADSZ 


EXTENSION RADS@ 


28 file entries (max) 
9 words each with this 
format: 


CREATION DATE 
USAGE 


LOCK 
| count 


START BLOCK # 


= File Type 
= Linked 
= Contiguous 


reaH 


3 words unused 


4 word header 


36 word bit map of entire DECtape (a logical 
ORing of all File Bit Maps) 
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CHAPTER 6 


CARD READER 


Standard (80-column) data processing cards can be read in any one of three 
modes: ASCII, packed Hollerith, or binary. One card can be read (and the 
information on it stored) in any mode. 


6.1 ASCII MODE 


The card reader reads cards punched with the standard ASCII codes, as shown 
in Appendix B. One of three sets of codes may be used: 029, 026, or 1401 
EBCDIC. The code set for the system is specified during system generation. 
Cards punched in other formats are not acceptable to RSTS/E. The 
end-of-file card for RSTS/E contains a 12-11-0-l1 or a 12-11-0-1-6-7-8-9 
punch in card column 1. Reading an end-of-file card causes an END OF FILE 
ON DEVICE error (ERR = 11) to occur, which can be trapped with an ON’ ERROR 
GOTO statement. 


The RECOUNT variable (see Section 12.3.1, BASIC-PLUS Language Manual) 
contains the number of characters read following every input operation. In 
the ASCII read mode, trailing spaces are ignored and carriage return and 
line feed characters are appended making the value of the RECOUNT variable 
two more than the number of punched columns per card. Consequently, the 
RECOUNT variable can have a value between 2 (for a blank card) and 82 (for 


80 columns of data). For example, consider a card punched as follows: 
ARCNEECUT TRI MNODADRDCMIVWYV? 
few eh VAAN 2 Ye Ue 


(columns 1 to 26 are punched, 27 through 80 are _ blank); the following 
program executes as shown: 
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100 OPEN "CR:" AS FILE 1% 
110 INPUT LINE #13, AS 
120 PRINT LEN(AS) 

130 PRINT ">" AS "<" 

140 END 


RUNNH 


28 
>ABCDEFGH IJKLMNOPQRSTUVWXYZ 
< 


In this example the trailing spaces in card columns 27 through 80 are 
deleted, and the two characters, carriage return and line feed are added, 
making a total of 28 characters in the string AS. 


Cards can be read with INPUT, INPUT LINE or GET statements. If a card is 
misread, or contains any illegal punches, a USER DATA ERROR ON DEVICE error 
occurs. If the card is read with a Record I/O GET statement, the buffer 
contains data for each column punched, and any columns that contain illegal 
punches are stored as RUBOUT (ASCII 127) codes. Therefore, the program can 
determine in which column(s) the error(s) occurred. 


CARD READER 
6.2 PACKED HOLLERITH MODE 
In the packed Hollerith read mode, the value of the RECOUNT variable is 
always 80, since each of the 80 card columns corresponds to a single data 


byte and trailing spaces are not ignored. The value of each byte is the 
sum of the punched row positions, as shown in Figure 6-1. 


Associated Values of Rows 


#12 128 
#11 64 
#0 a2 
#1 1 
# 2 2 
# 3 3 
Rows #4 4 

#5 5 
# 6 6 
# 7 7 
# 8 8 
#9 16 

Columns 

BI 0 


T 7 6 5 4 3 2 1 
 (wle[fe[e[ 7] 
8 4 2 


VALUE 128 64 32 16 1 


DIAGRAM #1 


Figure 6-1 
Packed Hollerith Read Mode 


Notice that the associated values of rows 1 through 7 are simply 1 through 
7 respectively. Only one of these seven rows can be punched per column. 
If none of these seven rows is punched, the value of the byte is 0. 
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6.3 BINARY MODE 
The binary read mode associates two data bytes with each card column. 
Therefore, the value of the RECOUNT variable is always 160. Once again, 


the value of each byte is the sum of the punched row positions, as shown in 
Figure 6-2. 


Associated Values of Rows 


#12 — — 8 
#11 ae 
#0 SECOND BYTE SnD 
#1 ' eres | 
#2 _s 128 
#3 64 
Rows #4 32 
#5 2 16 
#6 FIRST BYTE 8 
#7 4 
#8 2 
#9 2 oe A 


Columns 


7 6 5 3 2 1 0 
| eee 


SECOND BYTE FIRST BYTE 


DIAGRAM #2 


Figure 6-2 
Binary Read Mode 
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6.4 SETTING READ MODES 


A read mode is specified in an OPEN statement (with the MODE option) or a 
GET statement (with the RECORD option). The difference between specifying 
the read mode in a MODE option and in a RECORD option is discussed below. 
The corresponding values of the expressions in the MODE and RECORD options 
are listed in Table 6-3. The default mode is 0 (ASCII). When a MODE or 
RECORD option is used, the expression parameter must be specified; failure 
to do so results in an error message. 


CARD READER 


Table 6-3 
Specifying Read Modes 


MODE or RECORD Expression Specified Read Mode 


MODE 0 ASCII 
MODE 1 Packed Hollerith 
MODE 2 Binary 


OPEN 
Statement 


RECORD 257 Packed Hollerith 
RECORD 258 Binary 


GET 
Statement 


} RECORD 256 ASCII 


60 OPEN "CR:" FOR INPUT AS FILE 2%, MODE 1% 
110 GET #2%, RECORD 258 


Line 60, above, specifies the packed Hollerith read mode and line 110 
specifies the binary read mode of operation for inputting the information 
on the first card. 


A read mode specified in an OPEN statement supersedes previous read mode 
specifications. A read mode specified in a GET statement, however, 
overrides previous read mode specifications in the program for one card 
only. These concepts can best be illustrated by an example. Consider the 
program segment shown below. 


CARD READER 


Specified Read Mode 
at This Point 


100 OPEN "CR:" FOR INPUT AS FILE 1%, MODE 1% Hollerith 
200 GET #1%, RECORD 256% ASCII 

300 GET #13 Hollerith 
350 CLOSE 1% ! OPTIONAL CLOSE IN THIS CASE 

400 OPEN "CR:" FOR INPUT AS FILE 6%, MODE 03% ASCII 

500 GET #68% ASCII 

600 GET #6%, RECORD 258% Binary 


700 CLOSE 6% 


After line 100, above, sets the read mode to Hollerith, line 200 overrides 
it, setting the read mode to ASCII temporarily. When line 300 is executed 
without a RECORD option, however, the read mode reverts to the OPEN 
mode -- in this case, Hollerith. The next OPEN statement (line 400) 
Supersedes the previous one, setting the read mode to ASCII permanently. 
Line 500 is executed without a RECORD option, so the next card is read also 
in ASCII read mode. Closing a CR file (line 700), of course, cancels’ the 
card reader's read mode. When a file has been closed, executing an OPEN 
statement is the only way to re-establish a read mode. 
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CHAPTER 7 


SYS SYSTEM FUNCTION CALLS AND THE PEEK FUNCTION 


7.1 GENERAL SYS SYSTEM FUNCTION CALLS 


SYS system function calls allow a user program to perform special 1/0 
functions, to establish special characteristics for a job, to set terminal 
characteristics, and to cause the monitor to execute special operations. 


The specified SYS format is employed for two reasons. One, the calls are 
unique to the BASIC-PLUS implementation of the BASIC language. As such, 
the calls are system dependent and have calling format different from any 
BASIC language call. Second, the SYS format allows the usage of a variable 
number of parameters. 


SYS calls are separated into two classes: privileged and non-privileged. 
The privileged calls can be used only by a _ privileged user or by a 
privileged program. The non-privileged calls can be used by anyone and are 
completely safe in the sense that their misuse can do no damage to other 
programs. 


7.1.1 SYS System Function Formats And Codes 

The general format of the SYS call is as follows: 
VS = SYS(CHRS(F) + OS) 

where: 
V$ is the target string returned by the call 
F is the SYS system function code 


os is the optional (by function code) parameter string passed 
by the call 


Function codes denoted by F in the general format are from zero through 
nine, inclusive. SYS calls which specify a code outside of these numbers 
or which pass a zero length string generate the ILLEGAL SYS() USAGE error 
(ERR = 18). The following list summarizes the codes and their usages. The 
subsequent pages describe the usage, calling format, and purpose of the 
calls. 


Function 
Code (F) 


0 


1 
2 
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Usage 


Cancel “O effect on console terminal 
Enter tape mode on console terminal 
Enable echoing on console terminal 
Disable echoing on console terminal 


Enable single character input mode (ODT submode) 
console terminal 


Exit to editor with no READY message 
SYS call to the file processor 

Get core common string 

Put core common string 


Exit to editor and set up NONAME program 


on 
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7.1.2 General SYS System Function Calls 


7.1.2.1 Cancel “O Effect On Console Terminal - Not Privileged (F=0) 


Data Passed: 


Byte(s) Meaning 
1 CHR$ (0%), the cancel “O effect code 
2 Optional. If specified, CHRS$ (N%) where N% is the 
number of the channel on which the system executes 
the call. 


Data Returned: The target string is equivalent to the passed string. 
Discussion: 

This call cancels the effect of the user typing a CTRL/O combination 
at the program's console terminal. If the call is in the form 
SYS (CHR$ (0%) + CHRS(N%)), the system performs the action on _ the 


terminal open on channel N%. See Section 3.7 of the RSTS-11 System 
User's Guide for a description of the CTRL/O combination. 


7.1.2.2 Enter Tape Mode On Console Terminal - Not Privileged (F=1) 


Data Passed: 


Byte(s) . Meaning 
1 CHR$ (1%), the enter tape mode code 
2 Optional. If specified, CHRS$(N%) where N% is the 
number of the channel in which the system executes 
the call. 


Data Returned: The target string is equivalent to the passed string. 
Discussion: 


The action of this call is the same as that of the TAPE command 
described in the RSTS-1l1 System User's Guide. If the call is in the 
form SYS(CHR$(1%) + CHRS(N%)), the system performs the action on _ the 
terminal open on channel N%. 
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7.1.2.3 Enable Echoing On Console Terminal - Not Privileged (F=2) 


Data Passed: 


Byte(s) Meaning 
1 CHRS$ (2%), the enable echoing code 
2 Optional. If specified, CHRS$(N%) where N% is the 
number of the channel on which the system executes 
the call. 


Data Returned: The target string is equivalent to the returned string. 
Discussion: 
This code cancels the effect of SYS calls with codes l and 3. If the 


form of the call is SYS(CHR$(2%) + CHRS(N%)), the action is performed 
on the terminal open on channel N%. 
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7.1.2.4 Disable Echoing On Console Terminal - Not Privileged (F=3) 


Data Passed: 


Byte(s) Meaning 
1 CHR$ (3%), the disable echoing code 
2 Optional. If specified, CHRS$(N%) where N% is. the 
number of the channel on which the system executes 
the call. 


Data Returned: The target string is equivalent to the passed string. 
Discussion: 


This call prevents the system from echoing information typed at the 
console terminal. As a result, information such as a password is kept 
secret but accepted as valid input by the system. If the form of the 
call is SYS(CHR$(3%) + CHRS$(N%)), the action is performed at the 
terminal open on channel N#%, 
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7.1.2.5 Enable Single Character Input Mode (ODT Submode) On Console 
Terminal - Not Privileged (F=4) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (4%), the enable single character input mode 
code 
2 Optional. If specified, CHR$(N%) where N% is the 
number of the channel on which the system executes 
the call. 


Data Returned: The target string is equivalent to the passed string. 
Discussion: 


Allows a single character to be accepted as input from the terminal. 
Normally, the system waits until a line terminated by a RETURN, LINE 
FEED, FORM FEED, or ESCAPE character has been typed before accepting 
input. In single character mode, a character typed at the terminal is 
passed immediately to the program by the next keyboard input request 
statement without waiting for the delimiting character. 


This function must be enabled prior to every input request statement 
that passes a single character to the program. A GET statement is 
used as the input request statement. (INPUT or INPUT LINE statements 
cause repeated generation of the input request until a line terminator 
is detected and, therefore, must not be used.) 


If a program performs other lengthy operations before it executes 
either another SYS call and GET statement or other input/output 
operation at the terminal, it allows time for the user to type more 
than one character. To provide for such a possibility, the program 
should examine the system variable RECOUNT after executing each GET 
statement. This procedure determines how many characters the user 
typed between keyboard input operations and enables the program to 
process all the characters without losing any. 


Since this function is used in the system program ODT.BAS, it is 
sometimes referred to as “ODT submode". If the form of the call is 
SYS (CHR$ (4%) + CHRS$(N%)), the action is performed on the terminal open 
on channel N&%. 
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7.1.2.6 Exit To Editor With No READY Message - Not Privileged (F=5) 
Data Passed: 
Byte(s) Meaning 


1 CHRS$ (5%), the exit with no READY code 


Data Returned: No data is returned. 
Discussion: 
This call causes the same effect as the END statement, except that it 


can appear anywhere in the program and does not cause a READY message 
to be printed. 


7.1.2.7 FIP Function Call - Both Privileged and Not Privileged (F=6) 


See Section 7.2 for a description of SYS calls to the file processor. 


7.1.2.8 Get Core Common String - Not Privileged (F=7) 


Data Passed: 
Byte (s) Meaning 


1 CHR$(7%), the get core common string code 


Data Returned: The target string is the contents of the core common 
area. 


Discussion: 

Allows a program to extract a single string from a data area loaded by 
another program previously run by the same job. The data area is 
“called the core common and is from 0 to 127 8-bit bytes long. Refer 
to SYS function code 8. 
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7.1.2.9 Put Core Common String - Not Privileged (F=8) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (8%), the put core common string code 
2-128 The string to put in the core common area 


Data Returned: The target string is the passed string. 
Discussion: 


Allows a program to load a single string in a common data area called 
core common. This string can be extracted later by another program, 
running under the same job and called via the CHAIN statement. The 
string is from 0 to 127 8-bit bytes long. If the string to be put 
into the core common area is longer than 127 bytes, the system sets 
the length of the core common string to 0. Refer to SYS function code 
7. 


This function provides a means for passing a limited amount of 
information when a CHAIN statement is executed. If a larger amount of 
information is to be passed, it must be written to a disk file and 
read back by the later program. 
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7.1.2.10 Exit To Editor And Set Up NONAME Program - Not Privileged 
(F=9) 


Data Passed: 
Byte(s) Meaning 


1 CHRS (9%), the exit and set up NONAME code 


Data Returned: The target string is equivalent to the passed string. 
Discussion: 

This function causes the same actions as the END statement placed in 
the code, and, in addition, clears the program out of memory. This is 


the proper method of stopping a program that is not to be rerun, 
Also, the same action is performed by the command NEW NONAME. 
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7.2 SYS SYSTEM FUNCTION CALLS TO FIP (FUNCTION CODE 6) 
The SYS function call whose code is 6 is a more specialized case of 
the general system function call. It is specialized by a subfunction 
code called the FIP code. The FIP code causes a dispatch call to be 
made to special resident or non-resident code that performs File 
Processing. 
The format of the call is: 

VS = SYS(CHRS (6%) + CHRS(FO) + OS) 
where: 

vs is the data (target) string returned by the call 

FO is the FIP function code 


os is the optional (by function) parameter string 


The general format of the target variable (V$) is: 


Byte(s) Meaning 
1 Job number times 2 
2 Value of Internal Function called (meaningless to 
general user) 
3-30 Data returned 
NOTE 


Thirty bytes are always passed _ back. 
Unused bytes are either internal data or 
0. 


The proper use of the FIP system function call requires that the user 
program build a parameter string to pass and that the program later 
extract the data from the returned string, called the target string. 
Each call returns a string of 30 bytes, each byte (or character) of 
which may or may not contain useful information. The descriptions of 
the FIP codes specify the contents of each useful byte in the string, 
from which the user determines whether the information contained is of 
interest. 


7.2.1 Building A Parameter String 


Some FIP calls require no parameters except the function and 
subfunction codes; other FIP calls require either variable length 
parameter strings or very simple parameter strings. For such FIP 
calls, it is usually easiest to set up and execute the function call 
in a single statement. The following sample statements show the 
procedure. 


AS = SYS(CHRS$ (6%) + CHRS$(-7%)) 
!ENABLE CTRL/C TRAP 
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!(NO PARAMETER STRING) 


A$ = SYS(CHR$ (6%) + CHRS$(-10%) + "DKO:FILE.EXT") 
!FILE NAME STRING SCAN 
! (VARIABLE LENGTH 
! PARAMETER STRING) 

AS = SYS(CHR$ (6%) + CHR$(-8%) + CHRS(1%)) 


!FCB/DDB INFORMATION 
! FOR FILE OPEN ON 

! CHANNEL 1 

! (SIMPLE PARAMETER 
! STRING) 


Many FIP calls require more complex data formats. For example, the 
kill a job FIP call, FO = 8, requires byte 3 to be the job number to 
kill, byte 27 to be 0, and byte 28 to be 255. A recommended method of 
building the complex parameter string to pass to a function is to 
dimension a 30 byte list (an integer array) and set the items in the 
list to values which map into those required in the parameter string 
format. The list can later be set to a character string by the CHANGE 
statement before it is passed as the parameter string of the FIP 
system function call. The resulting character string is in proper 
format and contains the correct byte values so that it can be placed 
as the parameter string of the FIP system function call. For example, 


10 DIM A%(30%) !the string is 30 bytes 

20 J% = 4% !kill job number 4 

30 A%(I%) = 0% FOR I% = 0% TO 30% !ZERO UNUSED ENTRIES 

ca A%(0%) = 30% !0th element is length of 
ist 

50 A%(1%) = 6% !SYS call code 6 (FIP call) 

60 A%(2%) = 8% !PFIP code 8 (kill job) 

70 A%(3%) = J% !job number to kill 

80 A%(27%) = 0% !tthis byte must be 0 

90 A%(28%) = 255% {this byte must be 255 


Following the code which builds the list is the CHANGE statement and 
the call itself, as shown below. 


100 CHANGE A% TO A$ !generates character 
3 !string from the 
‘ linteger list 
200 BS = SYS(AS) !invoke system function call 


7.2.2 Unpacking The Returned Data 


In the example above, the action performed (kill a job) rather than 
the data returned is of importance. However, many FIP calls return a 
data string which is the primary interest of the user. In such a 
case, the data in the string must be unpacked. 


As in the case of building the parameter string, there are two 
recommended methods of unpacking the returned string. If the user 
needs only a few pieces of the data, it may be easiest to operate 
directly on the returned string. For example, if the user wants only 
the 4-byte Radix-50 representation of a 6-byte string, the filename 
string scan FIP call (FIP code ~10) can be used as follows: 


SYS SYSTEM FUNCTION CALLS AND THE PEEK FUNCTION 
AS = MID(SYS(CHRS$ (6%) + CHR$(-10%) + S$), 7%, 4%) 


to extract bytes 7 through 10 of the returned string. To extract 
numeric data, ASCII or CVT$% functions can be used. 


In some cases, many pieces of the returned data are needed. In other 
cases, the string returned by the FIP call is needed later to set up 
another FIP call. In such cases, the user program can transform the 
returned string to a 30-byte list using a CHANGE statement, 


CHANGE AS TO A% 
or 
CHANGE SYS(...) TO A% 


When the returned string has been converted in this manner, it is 
necessary to do further conversions in order to get numeric data into 
a usable form. Take, for example, the data returned by a FIP code of 
15 (directory lookup on _ index). The layout of the data returned 
specifies that bytes 11 and 12 are the filename extension encoded in 
Radix-50 format. In order to convert those bytes into an ASCII 
string, to OPEN the file, for example, the RADS$ BASIC-PLUS function 
must be used on the two bytes converted to a single integer. The 
integer representation of each byte, however, occupies a full word, 16 
bits in length. Thus, list items number 11 and 12 appear as the 
following: 


15 7 g 
A%(11) | g Byte ll | 
15 7 g 


A%(12) [ g Byte 12 


A%(1l) contains the low byte portion of the Radix-50 word; A%(12) 
contains the high byte portion of the Radix-50 word. The two bytes 
must be combined into a single word and converted to the proper 
character string representation. This is accomplished by the 
following: 


S$ = RADS(A%(11) + SWAP%(A%(12))) 


The SWAP% function reverses the bytes (the low byte takes the high 
byte position and vice-versa) in an integer word. Graphically, the 
operation appears as follows: 


7 a g 15 7 g 


g Byte 12 — |SWAP% (A%(12)) —_ Byte 12 g 


Thus, byte 12 takes the high byte position in the word. The two words 
are then combined by the + operator to form one word. The RAD$ 
function performs the conversion on that one integer word to produce 
the 3~character string representation of the file name extension. 
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The character string is assigned to the character variable S$ and is 
in ASCII format. 

To convert a longer string from Rad © ASCII format, the above 
Procedure must be applied to each two bytes in the string. For 
example, the filename from FIP call 15 is returned in bytes 7 through 
10. In order to convert these bytes to ASCII format, use the 
following routine. 


Q 


AS = RADS(A%(7%) + SWAPS (A% (88) ) 
BS = RADS(A%(9%) + SWAPS (A% (10%) 
FS = AS + BS 


or, in a single statement, 


FS = RADS(A%(7%) + SWAP%(A%(8%))) + 
RADS (A$ (9%) + SWAP%(A%(10))) 
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7.2.3 Notation And References Used In FIP Call Descriptions 
Many FIP calls reguire that a project-programmer number (PPN) be 
specified in the calling string, and several return a PPN. Where such 
is the case, the PPN field is in the following general form. 

Bytes X-(X+1) PPN 
The value X is odd. The intended meaning of this notation is that 
byte X in the string holds the programmer number, and byte (X+1) holds 
the project number. For example, to set up a_ FIP call to zero an 
account on a disk (FIP code 13), the calling format shows 

Bytes 5-6 Project-programmer number 


If the call is to be set up in a 30-entry list, A%, then the format 
requires that 


A% (5%) 
A% (6%) 


programmer number 
project number 


Many of the FIP calls described in this chapter return or require 
integer data in two (consecutive) bytes of the returned data string. 
When this is the case, the field in the returned string is described 


in the format: 

Bytes X-(X+1) integer value 
If the return string is to be processed directly (that is, without 
changing it to an integer array), then the integer value of the two 
bytes can be obtained using the following statement. 

IS = SWAPS (CVTS% (MID(AS,X,2%))) 
where A$ holds the returned string. If the returned data string is 
first transferred to an integer array, A%, using the CHANGE statement, 
then the integer value can be obtained using the statement below. 

I% = A&(X) + SWAPS (A%(X+18) ) 
For example, the Get Monitor Tables (Part I) FIP call (FIP code -3) 
returns the address of monitor's job table in bytes 1l and 12. If A$ 
holds the returned string, then either of the following two routines 
put the address of the job table into the integer variable I%. 

I% = SWAPS (CVTS$% (MID(AS,11%,2%))) 


or 


CHANGE AS TO A% 
IS = A$¥(11%) + SWAPS (A%(12%)) 
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In some integer fields in the FIP calls, the value is a full 16-bit 
unsigned integer between 0 and 65535. The sign bit indicates an extra 
power of two rather than positive or negative. Since an integer value 
in BASIC-PLUS is between -32768 and +32767; any value greater than 
32767 must be stored as a floating point value. Assume that in some 
SYS call, an unsigned integer is returned in bytes 5 and 6, and that 
the returned string has been changed to an array, A%. As always, the 
high byte of the integer is in byte 6, the low byte in byte 5. The 
statement 


Q = 256.*A%(6%) + A¥%(5%) 


gets the full 16 bit value into the floating point variable, Q. Q is 
always positive. Note that replacing the 256.* with SWAP%() causes 
the expression to be first evaluated as a normal integer expression, 
and then changed to a floating point value. The resulting value is 
between -32768 and +32767. The 256.* forces the expression to be 
evaluated as a floating point number. 


To convert an unsigned integer to two bytes to pass to a SYS call also 
requires special processing. Assuming that Q holds the unsigned 
value, and that the value is to be placed in A%(53%) (low order) and 
A%(6%) (high order), then the most direct method of transformation is: 


At (6%) 
A% (5%) 


Q/256. 
Q-A% (6%) *256. 


On PDP-11 computers without FIS or FPP (floating-point hardware), 
division operations are relatively slow. On these machines, a faster 
method is: 


10 IF Q<32768.THEN Q% = Q 
ELSE IF Q = 32768. THEN Q% = 32767% + 1% 
ELSE Q = Q-65536. 

20 A%(5%) = Q% AND 2558 

30 A%(6%) = SWAPS (Q%) AND 255% 


The disadvantage of this second method is that it requires more code. 
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The filename string scan SYS function (FIP code ~10) is useful as a 
"front-end" for many FIP functions. Most of the FIP calls which 
require device or filename information in their parameter strings 
expect information in the format which the FIP -10 call returns it. 
For example, FIP code 17, lookup a file by name, expects its calling 
string to be passed in exactly the same format as that returned by the 
FIP -10 call, with a change of only four data bytes. The following 
routine sets up and executes the lookup call on the file 
DKO: INVENT.DAT[10,20] using the filename string scan FIP call. 


SET UP LIST ARRAY. 
SET UP VARIABLE. 


10 DIM A% (30%) 
20000 AS="DKO: INVENT. DAT[10,20]" 
20010 CHANGE SYS (CHR$ (6%) +CHR$ (-10%)+A$) TO A% 


— 


DO THE FNS CALL TO 
SET UP ARRAY PROPERLY. 
SET UP FOR 30 LONG. 
THIS IS A FIP CALL 
DISK LOOKUP BY NAME. 
SET INDEX TO ZERO. 

SET UP AS A STRING 
AND DO THE CALL. 


20020 A%(0%)=30% 

20030 A%(1%)=6% 

20040 A&%(2%)=17% 

20050 A%(3%) ,A% (4%) =0% 
20060 CHANGE A% TO A$ 
20070 CHANGE SYS(A$) TO A% 
32767 END 


om Ome Ome Om Ome cme oem ome 


In order to avoid redundancy in the descriptions in Section 7.2, any 
field for any of the calls which are either passed to or returned from 
the function in the same format as that returned by FIP code ~-10 are 
identified by a+ superscript after the field specification. For a 
detailed explanation of fields so identified, see Section 7.2.4.1. 


Table 7-1 is a quick reference index of the FIP functions in order of 
FIP code (FO). For detailed information on each of the functions, 
refer to the Section shown beside the name in the table. 
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Table 7-1 
FIP SYS Calls (by Sub-function Code) 


FUNCTION 
CODE (FO) 


PRIVILEGED 
STATUS 


FUNCTION NAME PAGE 


Terminating file name string scan 
Set special run priority 
Drop (temporary) privileges 
Lock/unlock job in core 

Set number of logins 

Add run-time system 

Remove run-time system 

Load run-time system 

Unload run-time system 

Name run-time system 

System shutdown 


-15 Yes Accounting dump 7-93 
-14 Yes Change system date/time 7-39 
-13 Yes Change priority/run burst/job size 7-54 
~12 No Get monitor tables - Part II 7-107 
-11 Yes Change file backup statistics 7-70 
~10 No Filename string scan 7-20 
~9 Yes Hangup a dataset 7-40 
-8 No FCB/DDB Information 7-108 
-7 No CTRL/C Trap enable 7-36 
-6 Yes(1) Poke core 7-88 
-5 Yes Broadcast to terminal 7-41 
-4 Yes Force input to terminal 7-42 
-3 No Get monitor tables - Part I 7-105 
-2 Yes Disable logins 7-43 
-1 Yes Enable logins 7-44 
0 Yes Create user account 7-60 

1 Yes Delete user account 7-62 

2 Yes Clean up a disk pack 7-48 

3 Yes Disk packs 7-45 
Yes TTYSET 7-64 

4 Yes Login 7-72 

5 Yes Logout 7-74 

6 Yes Attach 7-77 
Yes Reattach 7-79 

7 Yes Detach 7-75 

8 Yes Change password/quota 7-49 
Yes Kill job 7-51 

Yes Disable TTY 7-52 

9 No Return error messages 7-29 
10 No Assign/reassign device 7-30 
ll No Deassign device 7-32 
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Table 7-1 (Cont.) 


Wresuee 


FIP SYS Calls (by Sub-function Code) 


FUNCTION PRIVILEGED 
CODE (FO) STATUS FUNCTION NAME 


Deassign all devices 

zero a device 

Read or Read and Reset Accounting 
Data 

Directory lookup on index 

Special magtape directory lookup 


Set terminal characteristics 

Disk directory lookup on filename 

Disk wildcard directory lookup 

Send a message 

Declaring a receiver and receiving 
a message 

Remove from receive table 

Enable/disable disk cacheing 

PEEK function 


The privileged status column indicates whether the SYS call can be 
used only by a privileged user or by any user. A non-privileged user 
who attempts to call a privileged SYS function always receives’ the 
ILLEGAL SYS() USAGE error (ERR = 18). The notation BOTH in the 
privileged status column indicates that some facilities of the 
specified function are available to a non-privileged user, while the 
privileged user has a more powerful set, 
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7.2.4 General Utility SYS Calls To FIP 


The SYS calls to the file processor described in this section are 
available to both privileged and non-privileged users. 


7.2.4.1 File Name String Scan - Not Privileged (FO=-10) 


Data Passed: 
Byte (s) 
1 


2 


Data Returned: 


Byte(s) 


23-24 


Sets 


(FO=-23) 


Meaning 
CHRS (6%), the SYS call to FIP 
CHRS$(-10), the filename string scan code. 
CHR$(-23) is the same as CHR$(-10) except that the 
scan terminates on certain characters. See 
discussion. 


Character string to scan; can be any length. 


the STATUS variable and returns the following. 
Meaning 
Internal coding 


Project-programmer number (0 means the current 
account) 


File name in Radix-50 format 

Filename extension in Radix-50 format 

Not used 

If no protection code is found, this byte is 0. 
Otherwise, this byte is 255 and byte 22 contains 
the protection 


Protection code when byte 21 is 255 


Device name in ASCII format or 0 if none is found. 
For example, DK and DT 


Device unit number if byte 26 is 255 


If this byte is 0, no explicit unit number was 
found for the device. If this byte is 255, the 
value in byte 25 is the explicitly specified 
device unit number. The 255 value here indicates 
that a zero in byte 25 is explicitly unit 0 of the 
device. 
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Byte(s) Meaning 
27-28 First flag word. See discussion. 
29-30 Second flag word. See discussion. 


Possible Errors: 
Meaning ERR Value 


ILLEGAL FILE NAME 2 
The character string scanned 
contains unacceptable characters. 
See Section 9.1 of the BASIC- 


PLUS Language Manual for a 


description of a file specification. 


Discussion: 


The file name string scan function determines specific file syntax 
information (for example, whether a given file name is valid) and 
returns information in the format required for all other file and 
device related SYS calls. In addition, it provides a means of packing 
a string in Radix-50 format. 


The STATUS variable (see Section 12.3.5 of the BASIC-PLUS Language 
Manual) is set for the device type found in the string scanned. 


The following example demonstrates how a string can be converted to 
Radix-50 format by a user defined function and the file name string 
scan SYS call. 


10 DEF FNPOS(AS) = MID (SYS (CHRS$ (6%) + 
CHRS (~10%)+AS) ,7%, 4%) 
! PACK 6 CHARACTERS TO RADIX-50 


The function FNPOS returns a 4-character String which is the Radix-50 
representation of the first six characters of AS. (Note that no error 
handling is included and that errors can occur.) The file name string 
scan call is the only function in BASIC-PLUS which packs a string in 
Radix-50 format. To pack strings longer than six characters, the user 
must make multiple calls to the SYS function. 


The two words in bytes 27 and 28 and in bytes 29 and 30 hold easily 
accessible flags indicating exactly what fields in the source string 
were found and what kind of information they contained. For the 
Purposes of the discussion, it is assumed that the returned string was 
converted by a CHANGE statement to an integer array, M%(30%). The 
flag words are then created by doing the proper arithmetic operations 
on the bytes, as shown: 


flag word 1: S0% 
flag word 2: S1% 


M% (27%) +SWAPS (M% (283) ) 
M% (29%) +SWAPS (M% (308) ) 
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Once these two words are created, the data coded into them is 
accessible by means of an AND operation between the word and the bit 
relating to a particular piece of information (see Section 2.8.7 for 
information about the AND operation). Each bit of the PDP-11 word can 
be used to hold a YES or NO answer. In the case of S0%, only the 
high-order 8 bits are used. In the case of $1%, all 16 bits are used. 


Flag word 1 is redundant; that is, all information returned in flag 
word 1 is also in flag word 2. Flag word 2 holds much more 
information than flag word l. 


In the following discussion, it is assumed that bytes 27 and 28 have 


been put into S0% and bytes 29 and 30 have been put into S1% as 
described above. 


7-22 
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Flag word 1: where S0% = 


Bit 


8 


10 


1l 


12 


13 


15 


Comparison 


SO AND 256%<>0$% 


SO% AND 256% = 08% 


SO% AND 512%<>0% 


SO% AND 512% = 0% 


S0% AND 1024%<>0% 


S0% AND 1024% = 0% 


S0% AND 2048%<>0% 


S0% AND 2048% = 0% 


S0% AND 4096%<>0% 


SO% AND 4096% = 0% 


S0% AND 8192%<>0% 


S0% AND 8192% = 0% 


S0%<0% 


M% (27%) +SWAPS (M3 (288) ) 


Meaning 


Filename was found in the source’ string 
(and is returned in Radix-50 format in 
bytes 7 through 10) 


No filename found 
A dot was found in source string 


No dot was found in_- source string 
implying that no extenson could have 
been specified either 


A project-programmer number was found in 
source string 


No project-programmer number was found 


A left angle bracket (<) was found in 
source string implying that a protection 
code was found 


No left angle bracket (<) was found (no 
protection was specified) 


A colon (but not necessarily a device 
name) was found 


No colon was found implying that no 
device could have been specified 


Device name was specified and specified 
device name was a logical device name 


Device name (if specified) was an 
absolute (non-logical) device name (if 
device name was not specified, this will 
be 0) 


Source string contained wild card 
characters (either ? or * or both) in 
filename, extension or project- 
programmer number fields. In addition, 
the device name specified, though a 
valid logical device name, possibly does 
not correspond to any of the logical 
device assignments currently in effect. 
The user program must extract the device 
name and attempt to access the unit. 
(See Section 7.2.16.4 for a description 
of wild card file specifications.) 
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Flag Word 2: where S1% = M% (29%) +SWAPS (M% (308) ) 


Bit Comparison Meaning 
0 S1% AND 1%<>0% File name was found in the source string 
S1% AND 1% = 08% No file name _ was found (and the 


following two comparisons return 0) 


1 S1% AND 2%<>0% File name was’ an * character and is 
returned in bytes 7 through 10 as the 


Radix-50 representation of the string 
"22?7?2?2?2". 


eorsas 


S1% AND 2% = 0% File name was not an * character 
2 S1% AND 4%<>0% Filename contained at least one ? 
character 
S1% AND 4% = 0% Filename did not contain any ? 
characters 
3 S1% AND 8%<>0% A dot (.) was found 
S1% AND 8% = 0% No dot was found implying that no 
extension was specified (and the 


following three comparisons return 0) 


4 S1% AND 16%<>0% An extension was found (that is, the 
field after the dot was not null) 


S1% AND 16% = 0% No extension was found (the field after 
the dot was null - the following two 
comparisons return 0) 


5 S1% AND 32%<>0% Extension was an * character and is 
returned in bytes 11 and 12 as the 
Radix-50 representation of the string 


"??? " 
S1% AND 32% = 0% Extension wasS not an * character 
6 S1% AND 64%<>0% Extension contained at least one ? 
character 
S1% AND 64% = 0% Extension did not contain any ? 
characters 
7 S1% AND 128%<>0% A project-programmer number was found 
S1% AND 128% = 0% No project-programmer number was found 


(the following two comparisons return 0) 


10 


11 


12 


13 


14 


15 


(1)Note that if the project-programmer number was of the 
8 and bit 


then 


SYS 


S1% AND 


51% AND 


AND 


AND 
AND 
AND 


AND 


AND 


51% AND 


S1% AND 


S1% AND 


S1% AND 


S1% AND 


$1% AND 


8$1%<0% 


both bit 


values. 
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256%<>08% 


256% = 08% 


512%<>0% (1) 


512% = 0% 
1024%<>0% 
1024% = 0% 
2048%<>0% 


2048% = 0% 


4096%<>0% 


4096% = 0% 


8192%<>0% 


8192% = 0% 


16384%<>0% 


16384% = 0% 


Project number was an * character (that 
is the projelct-programmer number was of 
the form [*,PROG]) and is returned in 
byte 6 as 255 


Project number was not an * character 
Programmer number was an * character 
(that is, the project-programmer number 
was of the form [PROJ,*] and is returned 
in byte 5 as 255 

Programmer number was not an * character 
A protection code was found 


No protection code was found 


The protection code currently set as 
default by the current job was used 


The assignable protection code was not 
used (protection code given is either 
the system default, 60, or that found in 
the source string) 


A colon (:), but not necessarily a 
device name, was found in the source 
string 


(no device could have 
the following three 


No colon was found 
been specified); 
comparisons return 0 


A device name was found 


No device name was found; 
two comparisons return 0 


the following 


Device name specified was a _ logical 
device name 
Device name specified was an actual 
device name 
The device name specified was logical 
and is not assigned to some actual 
device; the logical name is returned in 
bytes 23 through 26 as a Radix-50 
string. 

form [*,*], 


9 of the data byte returned are non-zero 
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S1%>=0% The device name specified, if any, was 
either an actual device name, or a 
logical device name to which a value has 
been assigned; the physical device name 
is returned in bytes 23 through 26 as 
described above 


Since flag word 2 contains all the information returned in flag word 1 
plus more information, it is the more useful of the two words. The 
following program uses this word. It prints out a list of all the 
bits returned in the word. 


5S DIM Mecszex>d ' SET LIF AN ARRAY TC RETURN TO 
1@ PRINT "STRING TO SCAN"; 

26 INPUT LINE S¢ 

26 SE=CV¥TS$$cS$, -425 ' GET RIC OF GARBAGE BYTES 

40 CHANGE SYSCCHRECEX+CHREC-10%904+5#) TO Me 

S@ SLM=MKC 29K +SWAP CMC Sete 2 


400 IF S1% AND 1% THEN = PRINT "FILENAME FOUND" 
410 IF S$1% AND 24 THEN = PRINT “FILENAME WAS AN +" 
420 IF S2k AND 4% THEN = - PRINT "FILENAME HAD / 775" 
430 IF $1% AND 8% THEN = -FRINT "DOT ¢. > FOUND" 


146 IF S41 AND 16% THEN PRINT "NON-NULL EXTENSION FOUND" 
15@ IF S4% AND Zee THEN PRINT “EXTENSICN WAS “4 * 

166 IF S4% AND 64% THEN PRINT "ESTENSION HAD “2° s" 

176 IF S4% AND 126: THEN PRINT "“PPN FOUN" 

180 IF S41 AND 256% THEN PRINT “PROJECT NUMBER WAS “# " 
196 IF S1% AND Saen THEN PRINT "PROGRAMMER NUMBER WAS 7" 


20@ IF Sik AND 1@24% THEN PRINT "PROTECTION COGE FOUND" 
21@ IF S12 ANG 2aden THEN FRINT "ASSIGN’ O PROTECTION USED" 
22@ IF Sie AND 46960 THEN PRINT "COLOM ¢:> FOUND" 

Z23@ 1F Ste AND 192% THEN PRINT "CEVICE NAME FOUND" 

240 1F Sik AND 1ézedn THEN PRINT "DEVICE NAME WAS LOGICRL" 


256 IF Sandan THEN PRINT “DEVICE MAME WAS NOT ASSIGN? oe 
266 IF Sik AND 4@96% THEN 
IF Slecge THEN PRINT "“STATUS’ HAS BEEN SET" 
496 PRINT FOR I#s4e TQ ex 
566 GOTO 14 


zer6" END 
The following examples show some of the above messages: 


STRING TO SCAN? ABCDEF. EXT 
FILENAME FOUND 

bOT ¢. > FOUND 

NON-NULL EXTENSION FCUNE 


STRING TO SCAN? SY: FILENM. CEX 
FILENAME FOUND 

DOT ¢.3 FOUND 

NON-NULL EXTENSION FOUNE 
COLON ¢:> FOUND 

DEVICE NAME FOUND 

“STATUS’ HAS BEEN SET 
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STRING TO SCAN? SY:FILENM. EXTC 41, 203) 
FILENAME FOUND 

BOT ¢.> FOUND 

NON-NULL EXTENSION FOUND 

PPN FOUND 

COLON ¢:3 FOUND 

DEVICE NAME FOUND 

“STATUS” HAS BEEN SET 


STRING TO SCAN? SY: FILENM. EXT 2, 162 1¢52> 
FILENAME FOUND 

DOT ¢. > FOUND 

NON-NULL EXTENSION FOLUNE 

PPN FOUND 

PROTECTION CODE FOUND 

COLON ¢:> FOUND 

DEVICE NAME FOUND 

“STATUS’ HAS BEEN SET 


STRING TO SCAN? SY: FILENNM. EXTC*®, 2843 
FILENAME FOUND 

DOT «.> FOUND 

NON-NULL EXTENSION FOUND 

PPN FOUND 

PROJECT NUMBER WAS *#¢ 

COLON ¢:3 FOUND 

DEVICE NAME FOUND 

“STATUS” HAS BEEN SET 


STRING TO SCAN? SYV-F © 
FILENAME FOUND 

DOT <. » FOUND 

NON-NULL EXTENSION FOUND 
EXTENSION WAS “7 

COLON ¢:> FOUND 

DEVICE NAME FOUND 


“STATUS” HAS BEEN SET 


STRING TO SCAN? 


STRING TO SCAN? SY: FILE??. EXT 
FILENAME FOUND 

FILENAME HAD “2°5 

DOT ¢. > FOUND 

NON-NULL EXTENSION FOUND 
COLON ¢:> FOUND 

DEVICE NAME FOUND 

“STATUS” HAS BEEN SET 


STRING TO SCAN? :A 
FILENAME FOUND 

COLON ¢:> FOUND 
“STATUS” HAS BEEN SET 
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The STATUS variable is set or not set depending on the presence or 
absence of a device in the string scanned. The following three 
conditions pertain. 


a. When no device name is found in the string (no colon is 
found), the STATUS is random. This condition pertains when 
bit 12 of flag word 2 tests as equal to 0. 


b. When the device name is logical and untranslatable (an actual 
device is not assigned), STATUS is random. This condition 
pertains when bits 12, 13 and 14 of flag word 2 test as not 
equal to 0 and bit 15 tests as on (S1%<0%). 


c. When the device name is either an actual device name or is 
logical and translatable (an actual device is assigned), 
STATUS is set for the device. This condition pertains when 
bit 12 tests as not equal to 0 and bit 15 tests as equal to 0 
(S1%>=0%) . 


Line 260 of the sample program shows the test to determine when STATUS 
is set by the call. 


The file name string scan using CHRS$(-23%) in place of CHRS$(-10%) 
terminates without error on the following characters. 


(equality sign) 


/ (slant) 

; (semi-colon) 
, (comma) 

end of string 


The number of unscanned characters is returned in the BASIC-PLUS 
variable RECOUNT. For example, 


SS$=SYS (CHRS (6%) + CHRS$(-23%) + "SY: [1,4]ABC<40>") 


returns the data as described above for CHRS$(-10%) and RECOUNT equals 
0. The following call 


SS = SYS(CHRS (6%) + CHRS$(-23%) + "SY: [1,4] ABC<40>,DT:DEF") 


returns the data described above for the string "SY: [1,4]ABC<40>" with 
RECOUNT equals 7. (The scan terminates on the comma between file 
names.) 


Any other characters, including the angle bracket character (<), 
generate an error and none of the data is returned. Thus, the call 
with CHR$(-23%) simplifies the task of decoding command strings with 
multiple file names. 
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7.2.4.2 Return Error Message - Not Privileged (F0=9) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$(9), the return error message code 
3 CHR$(E%), where E% is the RSTS ERR variable number 


and is between 0 and 127 


4-30 Not used 


Data Returned: 


Byte(s) Meaning 
1 The current job number times 2 
2 The current keyboard number times 2 
3-30 Error message padded to length 28 with CHRS(0$%) 


characters. 
Possible Errors: No errors are possible. 


Discussion: 


This SYS system function call extracts error message text from the 
file ERR.SYS stored under account [0,1] or in the RSTS.CIL file if 
ERR.SYS does not exist. The text is associated with the value of the 
ERR variable passed as byte 3 of the call. The number in byte 2 of 
the returned string is two times the number of the keyboard involved 
in generating the error. This is an exception to the conventional 
contents of byte 2 which usually contains the job number times 2. A 
Sample usage of the call is to print the system header line containing 
the system name and the local installation name. To do this, the 
character representation of the ERR value of 0% is used in the call. 


10 INPUT "ERROR NUMBER";E% 

20 S$=SYS (CHRS (6%) +CHRS (9%) +CHR$ (E%) ) 

30 S1$=MID(S$,3%, INSTR(3%,S$,CHRS (0%) )-3%) 
40 PRINT S1$ 

50 PRINT FOR I%=1% TO 2% 

60 GOTO 10 

32767 END 


To extract the message text from the data returned by the SYS call, 
the program executes an INSTR function based on the NUL byte (FILL 
character) indicating the end of the text. The MID substring of the 
returned data string, starting at byte number 3, extracts the number 
of bytes according to the value returned by the INSTR function. 


Error numbers used in the call can include those associated with 
recoverable and non-recoverable errors. 


RUNNH 
ERROR NUMBER? 0 
RSTS VO6A-01 SYSTEM #880 
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7.2.4.3 Assign/Reassign Device - Not Privileged (F0=10) 


Data Passed: 


Byte (s) 


Data Returned: 


Meaning 
CHRS (6%), the SYS call to FIP 
CHRS$ (10%), the assign/reassign device code 
Not used 


Must be 0 for assign; for reassign, must be 
job number to reassign the device to 


Must be 0 
Not used 
Device name (DT, PR, PP, MT, CR, LP, KB) 


+ nomhar 
GC fuUuMiwoe 


TInd 
Vila 


Unit number flag 


Not used 


No meaningful data is returned. 


the 
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Possible Errors: 


For the assign call 


NOT A VALID DEVICE 
The device name specified in bytes 23 
and 24 is a logical device name which 
is currently not assigned. 


DEVICE NOT AVAILABLE 
The device specified is currently 
assigned or in use by another job. 


For the reassign call 


ACCOUNT OR DEVICE IN USE 
The device specified is currently 
open or has an open file. 


NOT A VALID DEVICE 
The device name specified in bytes 23 
and 24 is a logical device name which 
is currently not assigned. 


DEVICE NOT AVAILABLE 
The device specified is currently 
assigned to another job or is in 
use by another job. 


Example: 


10 A$ = SYS (CHRS (6%) +CHRS (10%) +SPACES (4%) + 
CHRS (0%) +CHRS (0%) +SPACES (14%) + 
"LP" + CHRS$ (1%) +CHRS (255%) ) 

i ASSIGN LPi: TO CURRENT JOB. 

20 X%=4% 

30 AS=SYS (CHRS (6%) +CHRS$ (10%) +SPACES (4%) + 
CHRS (X%) +CHRS (0%) +SPACES (14%) + 
"LP"+CHRS (1%) +CHRS (2558) ) 

! REASSIGN LPl: TO JOB # X&%. 
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7.2.4.4 Deassign A Device - Not Privileged (F0=11) 


Data Passed: 


Byte (s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHRS$ (11%), the deassign a device code 
3-6 Not used 
7-8 Must be 0 
9-22 Not used 
23-24+ Device name 
25+ Unit number 
26+ Unit number flag 
27-30 Not used 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


NOT A VALID DEVICE 6 
The device name specified in bytes 23 
and 24 is not a valid device name. 


Discussion: 


This call performs the same action as the DEASSIGN system command 
described in the RSTS-l1l System User's Guide. 


Example: 


The following statement deassigns line printer unit 1 which is 
assigned to the current job. 


10 AS = SYS(CHR$(6%) + CHRS$(11%) + SPACES (4%) + 
CHRS (0%) + CHR$(0%) + SPACE$(14%) + 
"LP" + CHRS(1%) + CHRS$(255%)) 
! DEASSIGN LPl: 
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7.2.4.5 Deassign All Devices - Not Privileged (F0=12) 


Data Passed: 


Byte(s) Meaning 
1 CHR$ (6%), the SYS call to FIP 
2 CHR$ (12%), the deassign all devices code 
3-30 Not used 


Data Returned: No errors are returned. 


Possible Errors: No errors are returned. 


Example: 


The following statement deassigns all devices currently assigned 
the job. 


10 AS = SYS(CHR$(6%) + CHRS$(12$)) 


to 
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7.2.4.6 Zero A Device - Both Privileged and Not Privileged 


Data Passed: 


(F0=13) 


Byte (s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHRS$ (13%), the zero a device code 

3-4 Not used 

5-6 Project-programmer number (see note 1) 

7-10 Volume ID for volume label (ANSI format MT only) 
11-22 Not used 

23-24+ Device designator (Disk, magtape, or DECtape) 
25+ Unit number 

26+ Unit number flag 

27-30 Not used 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning 


INVALID FILENAME 
The device specified is a magtape set to 
ANSI format, and the volume ID specified 
in bytes 7-10 is either missing or invalid. 


CAN'T FIND FILE OR ACCOUNT 
The device specified is disk and the 
account specified in bytes 5 and 6 
does not exist on the device 


NOT A VALID DEVICE 
The device name specified is a 
logical name which is not currently 
assigned 


DEVICE NOT AVAILABLE 
The device is currently assigned or in 
use by another job or has a file open 


DEVICE NOT FILE STRUCTURED 


The device specified does not allow 
access by file name. 


7-34 


ERR 


Value 


30 
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Note 1: 


Only privileged users can specify an account other than their own 
account to be zeroed. Any values a non-privileged user specifies in 
bytes 5 and 6 are forced to the caller's own project-programmer 
number. zeroes in bytes 5 and 6 indicate the project-programmer 
number of the calling program. 


Note 2: 


When the zero a device SYS call is specified on magtape or DECtape, 
the entire medium is zeroed without regard to any project-programmer 
number. On DECtape, the directory is cleared. On magtape, the tape 
is rewound to LOAD POINT, three end of file marks are written, and the 
tape is rewound (See Section A.3.). 


Example: 


10 AS$=SYS (CHRS (6%) +CHRS (13%) +SPACES (2%) + 
CVTSS (0%) +SPACES (16%) +"SY"+CVTSS (0%) ) 
! ZERO MY OWN ACCOUNT ON THE SYSTEM. 
20 POS=10% : P2%=20% !IWANT TO ZERO [10,20] 
30 AS$=SYS (CHRS (6%) +CHR$ (13%) +SPACES (2%) + 
CHR$ (P1%)+CHRS (P0%) +SPACES (16%) +"SY"+ 
CVT$$ (08) ) 
! ZERO [10,20] ON THE SYSTEM. 
! IF PROGRAM IS NON-PRIVILEGED, ZEROES 
! CURRENT ACCOUNT 
40 AS=SYS (CHRS$ (6%) +CHRS (13%) +SPACES (20%) + 
"MT"+CVTSS$ (0%) ) 
! ZERO MT: 
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7.2.4.7 CTRL/C Trap Enable - Not Privileged (F0=-7) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS$ (-7%), the CTRL/C trap enable code 
3-30 Not used. 


Data Returned: No meaningful data is returned. 
Possible Errors: No errors are possible. 


Discussion: 


After this FIP function is executed in the user program, the Run Time 
System treats the first CTRL/C subsequently typed on any terminal 
belonging to the job as a trappable error (ERR=28). Upon execution of 
the trap, control is immediately passed to the numbered program 
statement which has been designated as the error-handling routine by 
the last execution of an ON ERROR GOTO statement. After the trap, 
CTRL/C trapping is disabled. If it is desired that CTRL/C trapping 
remain in effect, the SYS call must be executed again. 


Such trapping of CTRL/C, however, guarantees only that a defined set 
of statements is executed when CTRL/C is typed. It is not possible to 
resume execution at the exact point where the CTRL/C occurred. 


If certain critical sections of BASIC-PLUS code are to be completely 
immune to possible CTRL/C aborts, three actions must occur. 


a. The job must detach itself from its terminal. See the 
description of FIP code +7. 


b. The program must have CLOSED all channels on which other 
terminals in the job had been OPENed. 


c. The job must have DEASSIGNed any terminal which had been 
previously ASSIGNed to it. See the description of FIP code 
+11. : 


If the three actions occur, program execution under the job proceeds 
immune to any CTRL/C. 


After the job has completed its critical processing in the detached 
state, one of three actions can occur. 


a. The job can kill itself by means of FIP code +8. 
b. The job can find a free terminal (presumably the one from 


which it detached itself) and "force" into that terminal 
input buffer the character strings needed for logging into 
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the system and attaching the job to the terminal. (See the 
descriptions of FIP codes -4, +4, and +6.) 


c. The job can find a free terminal and use the REATTACH SYS 
cali to attach itseif to the terminal. (See the description 
of FIP code +6.) 

The following sample program shows the procedure. 


GET SET TO TRAP 
ENABLE “~C TRAPPING 


10 ON ERROR GOTO 100 

20 AS=SYS (CHRS (6%) +CHRS (-7$%) ) 
30 PRINT "HI "; 

40 SLEEP 10% ! WAIT AWHILE 
50 GOTO 30 


100 IF ERR<>28% THEN ON ERROR GOTO 0 

ELSE RESUME 110 ! LOOK FOR A CTRL/C 
110 PRINT "“C TRAPPED" 
120 SLEEP 103% 
130 GOTO 20 ! GO BACK TO LOOP 
32767 END 


The program prints "HI" at the keyboard every ten seconds until a 
CTRL/C is typed. Then it prints the "*C TRAPPED" message and a sleep 
operation for ten seconds before reenabling the CTRL/C trap and 
printing "HI". The SLEEP statement before reenabling the trap is 
included to allow the user to type a second CTRL/C and actually stop 
the program. 


Ordinarily, two CTRL/C characters typed very quickly at a terminal 
stop a program even if CTRL/C trapping is enabled. However, on a 
lightly loaded system, it is sometimes possible for the program to 
react quickly enough to the first CTRL/C that the second one can also 
be trapped. In this situation, the only means of stopping the job is 
through the kill job SYS call (or the KILL command in the UTILTY 
program). Thus, after the original trap, the user can stop the 
program by typing CTRL/C within ten seconds. It is recommended that 
programs which trap CTRL/C characters be designed to include a certain 
amount of time after a trap in which a second CTRL/C actually stops 
the program. 


When a CTRL/C is input from a terminal, further output is inhibited, 
Similar to the effect of the CTRL/O. This is true whether the error 
condition caused by CTRL/C is processed directly by the BASIC-PLUS 
editor or is handled by the user's program itself. When the CTRL/C 
error condition is processed by the editor, it reenables Output just 
prior to printing READY. When the CTRL/C error condition is trapped 
into the user's own error handling routine, the output to the terminal 
is reenabled just before executing the ON ERROR GOTO statement. 
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7.2.5 Privileged Utility SYS Calls 


The FIP calls described in this section are privileged calls; that 
is, they can be called only by a privileged user or by a privileged 
program. (See Section 1.2 for a discussion of privilege.) Any 
attempts to execute these calls by non-privileged users or programs 
result in the error ILLEGAL SYS( ) USAGE (ERR = 18). Other errors are 
specified in the individual descriptons. The functions described in 
Sections 7.2.5.2 through 7.2.5.11 are used by the UTILTY system 
program. Examples of their usage can be found in the source code of 
that program. 


7.2.5.1 Special Shutup Logout - Privileged (F0=-16) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$ (-16%), the special shutup logout code 
3-30 Not used 


Data Returned: No meaningful data is returned 


Errors Returned: Refer to the discussion. 


Discussion: 


This system function logs the current job off the system (as does the 
FIP system function call code 5) but, in addition, brings the CPU to 
an orderly halt at address 54 after the job is logged off the system. 


Before this FIP call can execute properly, several system conditions 
must be true. First, one and only one job can be running on the 
system when the SYS call is invoked. Next, the number of logins 
allowed on the system must be 1 (that is, LOGINS DISABLED. See 
Section 7.2.5.6). Next, no disks except the system disk can be 
mounted. Finally, no files can be open on the system disk. 


If all of these conditions are fulfilled, the system shuts down. If 
any are not true, any attempt to invoke this SYS call results in the 
error ILLEGAL SYS( ) USAGE (ERR = 18). 


This SYS call is used by the SHUTUP program. 
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7.2.5.2 Date And Time Changer - Privileged (FQ=-14) 


Data Passed: 
Byte (s) 

1 

2 


Data Returned: 


Discussion: 


Meaning 
CHR$ (6%), the SYS call to FIP 
CHRS$ (~14%), the date and time changer code 


CHR$(D%) where D% is in the required format to 
generate the date by the function DATES (D%). See 


Section 8.8 of the BASIC-PLUS Language Manual for 


a description of the DATES function. 


CHRS$ (SWAP%(D%)) where D% is the same value used in 
byte 3. This generates the high byte of the value 
used by the DATES(0%) function. 


CHRS(T%) where T% is in the required format to 
generate the time by the function TIMES (T%). See 


Section 8.8 of the BASIC-PLUS Language Manual for 


a description of the TIMES function. 

CHRS (SWAP%(T%)) where T% is the same value used in 
byte 5. This generates the high byte of the value 
used by the TIMES(0%) function. 


Not used. 


No meaningful data is returned. 
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7.2.5.3 Hang Up A Dataset - Privileged (FO0=-9) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$(-9%), the hang up a dataset code 
3 CHRS$(N%) where N% is the keyboard number of the 


line to hang up 


4 CHRS(S%) where S% is the number of seconds to wait 
before hanging up the line 


5-30 Not used. 


Data Returned: No meaningful data is returned. 
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7.2.5.4 Broadcast To A Terminal - Privileged (F0=-5) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS$ (-5%), the broadcast to a terminal code 
3 CHR$(N%) where N% is the keyboard number of the 


terminal to receive the message 


4-? MS is the message to broadcast; LEN(MS) can be 
greater than 27. The string must not be null. 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
Generated if LEN(MS) is 0. 


Discussion: 


The data broadcast is printed on the destination keyboard. The 
received message affects any output formatting being performed on the 
destination keyboard. System programs which use this function are 
TALK, PLEASE, BACKUP, and QUEMAN and UTILTY. 
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7.2.5.5 Force Input To A Terminal - Privileged (F0=-4) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS$ (-4%), the force input to a terminal code 
3 CHRS$(N%) where N% is the keyboard number of the 


terminal to receive the forced input 
4-? I$ is the input string to force to the terminal. 


The string must not be null. LEN(I$) can be 
greater than 27. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
Generated if LEN(I$) is 0. 


Discussion: 


The data forced is seen as input by the system. Other system programs 
besides UTILTY which use this function are BUILD, INIT, and CONTRL. 
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7.2.5.6 Disable Further Logins - Privileged (F0=-2) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$(-2%), the disable further logins code 
3-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
A non-privileged user attempts 
to execute this call. 


Discussion: 


This call sets the number of logins allowed on the system to l. If no 
jobs are active on the system, one user can successfully log into the 
System. However, once one user is logged in, any delimiter typed at a 
logged out terminal returns the NO LOGINS message. This call is used 
by the UTILTY and SHUTUP programs. 
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7.2.5.7 Enable Further Logins - Privileged (F0=-1) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS(-1%), the enable further logins code 
3-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
A non-privileged user attempts 
to execute this call. 


Discussion: 


This call sets the number of logins allowed to the number specified at 
start-up time - JOBMAX. The enable logins call is used by the UTILTY 
and INIT programs. 
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7.2.5.8 Disk Pack And Terminal Status - Privileged (F0=3) 


Data Passed: 


Byte (s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHRS$ (3%), the disk pack and terminal status code 
3 CHRS(N%); the following values of N% determine 
the resultant action. 
Value Action 
Any Odd Set terminal status. 
See FIP call 16. 
0 Mount a disk pack or cartridge 
2 Dismount a disk pack or cartridge 
4 Lock out a disk pack or cartridge 
6 Unlock a disk pack or cartridge 


For Mount, Dismount, Lock, and Unlock 


23-24+ Device name 
25+ Unit number 
26+ Must be 255. 
For Mount 
7-10+ Pack identification label in Radix-50 format 
? All bytes not specified are ignored. 


Data Returned: No meaningful data is returned. 
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Possible Errors: 
Meaning 


ACCOUNT OR DEVICE IN USE 
An attempt to dismount a 
disk which has an open file 


NOT A VALID DEVICE 
Device name specified is not 
valid. 


DEVICE HUNG OR WRITE LOCKED 
An attempt to mount a disk 
which is not write enabled 


ILLEGAL SYS() USAGE 
An attempt by a non-privileged 
user to execute this call; or an 
attempt to mount a disk which is 
aready mounted or which resides 
in a non-dismounted drive; or disk 
specified is the system disk. 


PACK IDS DON'T MATCH 
An attempt to mount a disk with 
an incorrect pack label. 


DISK PACK IS NOT MOUNTED 
An attempt is made to lock, unlock 
or dismount a disk which is not 
mounted. 


DISK PACK NEEDS 'CLEANING' 
The storage allocation table on the 
disk needs to be restructured since 
the disk was not properly dismounted 
when it was last used. Disk is logically 
mounted but cannot be accessed until 
cleaned by the CLEAN command of UTILTY 
system program or by the FIP call with 
code 2. 


FATAL DISK PACK MOUNT ERROR 
The disk is beyond recovery. For 
example, the cluster size is larger 
than 16 or the storage allocation 
table is unreadable. 


DEVICE NOT FILE STRUCTURED 
An attempt to lock, unlock, or 
dismount a disk currently opened 
in non-file structured mode. 


ERR Value 


3 


14 


18 


20 


21 


25 


26 


30 
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Discussion: 


Note that if byte 3 contains any odd value, the call is interpreted as 


a set terminal characteristics call and is exactly equivalent to FIP 


call 16 discussed in Section 7.2.8. This call is used by the SHUTUP, 
UMOUNT, and BATCH system programs. (The terminal characteristics form 
of the call is used by the TTYSET program.) For a discussion of disk 
management on RSTS/E, see Section 7.1.2 of the RSTS/E System Manager's 
Guide. 
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7.2.5.9 Clean Up A Disk Pack - Privileged (F0=2) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS$ (2%), the clean up a disk pack code 
3-22 Not used 
23-24+ Device name 


A zero in both bytes means the system disk 


25+ Unit number 
26+ Unit number flag 
27-30 Not used 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
An attempt to use this call by 
a non-privileged user; the 
device specified is not a disk; 
the disk is not locked; a file 
is open on the disk. 


DISK PACK IS NOT MOUNTED 21 
The disk is not yet mounted. 


CORRUPTED FILE STRUCTURE 29 
The link words in the directories 
are destroyed or completely meaningless. 


Discussion: 


A clean operation on an RK disk cartridge takes up to 30 seconds and 
on an RPO3 disk pack takes up to five minutes. See Section 7.1.2 of 
the RSTS/E System Manager's Guide, for a discussion of disk management 
and the clean operation. 
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7.2.5.10 Change Password/Quota ~- Privileged (F0=8) 


Data Passed: 


Byte (s) 


9-12 


13-14 


29-30 


Data Returned: 


Meaning 
CHRS$ (6%), the SYS call to FIP 


CHR$ (8%), the change password/guota, kill job, and 
disable terminal code 


Not used 

Project-programmer number. Zero for both values 
means the current account. See Section 7.2.3 for 
an explanation of the value of each byte. 

New password in Radix-50 format. All zeroes mean 
no change. See Section 7.2.4.1 for a description 
of converting strings to Radix-50 format. 

CHRS (N%) +CHRS (SWAPS (N%)), where N% is the number 
of blocks for the quota. Zero in this word means 
unlimited quota if byte 21 is 255. Otherwise, 
zero means no change. 

Not used 


CHRS$(255%) if the quota of 0 specified in bytes 13 
and 14 is valid rather than no change. 


Device name 

Unit number 

Unit number flag 
Not used 

Must be CHRS(0$%) 


Not used. 


No meaningful data is returned. 
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Possible Errors: 


Meaning ERR Value 


CAN'T FIND FILE OR ACCOUNT 5 
The account iS not present on 
the disk specified. 


NOT A VALID DEVICE 6 
Device specified is not valid. 


ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged user 
to execute this call or the device 
specified is not a disk. 


Discussion: 


Either the password or the quota can be changed individually. Also 
both can be changed in the same call. 
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7.2.5.11 Kill Job - Privileged (F0=8) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS$ (8%), the change password/quota, kill job, and 
disable terminal code 
3 CHRS$(N%) where N% is the number of the job to kill 
4-26 Not used 
27 Must be CHRS$(0%); this byte differentiates the 
kill job call from the disable terminal call 
28 Must be CHR$ (255%) 
29-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
The job number specified is 0 
or is greater than the system 
JOB MAXIMUM value. An attempt 
by a non-privileged user to 
execute this call. 


Discussion: 


There is only one proper way for a job to terminate itself under 
programmed control. The job must execute the kill FIP call on its own 
job number. The kill does all of the clean-up that the logout FIP 
call (FO0O=5) does, but this function can be executed under program 
control by any (privileged) program, whereas the logout call requires 
certain special conditions. Examples of this SYS call can be found in 
the ERRCPY, BATCH, SPOOL, and QUEMAN programs. 
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7.2.5.12 Disable Terminal - Privileged (F0=8) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS (8%), the change password/quota, kill job, and 
disable terminal code 
3 CHRS$ (N%), where N% is the keyboard number of the 
terminal to disable 
4-26 Not used 
27 Must be CHRS$(255%) to differentiate this call from 
the kill job call 
28 Must be CHRS$ (255%) 
29-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
Keyboard number is greater than the 
number of terminals on the system 
(NULINE) ; 

Keyboard number corresponds to a line 
used by a pseudo keyboard; 

Keyboard number relates to a terminal 
on a DH11]1 multiplexer line; 

The terminal is currently opened or 
assigned by a job; or 

The keyboard is the system console 
terminal (KBO:). 


Discussion: 


This FIP call disables a keyboard line. After this function has’ been 
executed, no input from the disabled keyboard is processed or echoed 
by the system, and output generated for the terminal is ignored. 
There is no complementary function in RSTS/E. Once a keyboard is 
disabled, it remains disabled until the next time the system starts 
time sharing. 
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Note that this function only disables keyboards connected to the 
PDP-11 with single line interfaces (KL11, DL11l, etc.). 


No system program (including UTILTY) currently uses this call. It is 
included at this point because of its relationship to the change 
password and kill job FIP calls. 
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7.2.6 Job Scheduling SYS Calls To FIP 


7.2.6.1 Priority, Run Burst And Size Maximum Changer - Privileged 
(FO=-13) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$(-13), the priority, run burst, and size 


maximum changer 


3 CHRS(J%), where J% is the job number affected or 
is -l1 to denote the current running job 


4 CHRS(A%) where A% is 0% to indicate no change to 
the parameter in byte 5 or is non-zero to indicate 
a change to the parameter as specified in byte 5. 


5 CHRS(P%) where P% is the value of the running 
priority and ranges from -128 to +128 in steps of 
8. 

6 CHRS (A%) where A% is 0% to indicate no change to 


the parameter in byte 7 or is non-zero to indicate 
a change to the parameter as specified in byte 7. 


7 CHRS (R%) where R% is the run burst. 


8 CHRS$(A%) where A% is 0% to indicate no change to 
the parameter in byte 9 or is non-zero to indicate 
a change to the parameter as specified in byte 9. 


9 CHRS(S%) where S% is the maximum size, in 
1024-word units, to which a job can expand and is 
between 2 and the current value for SWAP MAX on 
the system. 


Data Returned: No meaningful data is returned. 
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Possible Errors: 
Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged user 
to execute this call. 


Discussion: 


This system function allows a privileged user to give a running job an 
increased or decreased chance of gaining run time in relation to other 
running jobs, and to determine how much CPU time the job can have if 
it is compute bound. The CPU time is termed the job's run burst and 
is measured by the number of clock interrupts during which the job can 
run if it is compute bound. 


The size of a job at log in time is set at 2K and can grow during 
processing to a_ size limited by the value of SWAP MAX. SWAP MAX is 
determined at the start of time sharing operations by the system 
Manager. (Refer to the description of SWAP MAX given in the START and 
DEFAULT option discussed in Chapter 3.) The maximum size to which a 
job can grow can never be greater than the currently assigned value of 
SWAP MAX, which must be between 8K and 16K words. Therefore, the 
privileged user has the option of limiting the size to which a job can 
grow by specifying a value for S% between 2 and the maximum of SWAP 
MAX. 


Values for each of the variables in the parameter string must be 
specified. The value for A preceding the related parameter variable 
determines whether that Parameter changes or remains unchanged. 


The PRIOR system program provides a direct example of the use of this 
FIP call. The call is also used by the LOGIN, SPOOL, and RJ2780 
system programs. 


No error-checking is done by the System on the data passed by the 
user. Values are used as passed even if they generate illogical 
results. For instance, if a priority is specified which is not a 
multiple of 8, its value is truncated to the next lowest multiple of 
8. A priority greater than 128 is considered negative. Setting a 
job's run burst to 0 prevents the job from obtaining any run-time. 
Setting a (compute-bound) job's run-burst to some high number tends to 
lock out other jobs. However, setting S% to 255, or any value greater 
than the system SWAP MAX does not override the system maximum. 
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7.2.6.2 Set Special Run Priority - Privileged (F0=-22) 


Data Passed: 


Byte (s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHRS$ (-22%), the set special run priority call 
3-30 Not used. 


Data Returned: No meaningful data is returned. 
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Possible Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged 
user to execute this call. 


Discussion: 


This SYS function sets the special run priority bit in the job 
priority word. This action raises the priority of the job slightly 
above that of other jobs in its priority class. The priority bit is 
cleared whenever the job returns to the READY state. Thus, a 
privileged job can raise its priority without protecting against a 
user typing CTRL/C and retaining the higher priority. This FIP call 
is used by the QUE system program. 
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7.2.6.3 Lock/Unlock Job In Memory - Privileged (F0=-20) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$ (-20%), the lock/unlock job in memory code 
3 CHRS$(N%) where N% is 0 for lock and is 255 for 
unlock 
4-30 Not used. 


Data Returned: No meaningful data is returned. 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged user to 
execute this call. 


Discussion: 


This call prevents unnecessary swapping by forcing the job executing 
the call to remain in memory. This action is performed without 
affecting the job priority or run burst. The call merely eliminates 
the swapping time between run bursts. 


A program having certain time sensitive routines can lock itself in 
Memory. The duration of the locked time must be very short to prevent 
degradation of system performance. Depending on the memory 
configuration, a locked job can prohibit the system from swapping any 
other job into memory. If the job expands its size in memory, the 
system can swap it out of memory regardless of its locked status. 


The following sample code demonstrates the lock and unlock procedure. 


10 AS = SYS(CHRS (6%) + CHR$(-20%) + CHRS (0%) ) 
! LOCK JOB IN MEMORY 


100 A$ = SYS(CHRS$ (6%) + CHR$(-20%) + CHRS (255%) ) 
! UNLOCK JOB FROM MEMORY 
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7.2.6.4 Drop Temporary Privileges - Privileged (FO=-21) 


Data Passed: 


Byte (s) Meaning 
1 CHR$ (6%), the SYS call to FIP 
2 CHR$(-21%), the drop temporary privileges code 
3-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged user 
to execute this call. 


Discussion: 


This call allows a compiled program which has a privileged protection 
code to drop its temporary privileges. A program normally executes 
this call after it has used the special privileges to set itself up. 
The program can take advantage of built-in monitor protections (for 
example, file protection code arbitration) which are otherwise 
overridden by a program's temporary privileges. The call does not 
affect the permanent privileges of an account. Both the QUE and PIP 
system programs use this call. 


The foliowing sample code shows how a program might drop its temporary 
privileges. 


10 A$ = SYS(CHRS(6%) + CHR$(-228) 
! SET SPECIAL RUN PRIORITY 


20 OPEN "SYSTEM.FILS" AS FILE 1% 
! OPEN REFERENCE FILE, REGARDLESS OF PROTECTION 


30 AS = SYS(CHRS(6%) + CHRS$(-218) 
! DROP TEMPORARY PRIVILEGES 


40 OPEN "ACCT.FIL" AS FILE 2% 
! THIS FAILS IF FILE IS PROTECTED AGAINST THE 
! CURRENT ACCOUNT 
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7.2.7 Account Creation And Deletion SYS Functions 


7.2.7.1 Create User Account - Privileged (F0=0) 


Data Passed: 


Byte (s) Meaning 
1 CHR$ (6%), the SYS call to FIP 
2 CHRS$ (0%), the create user account code 
3-6 Not used 
7-8 Project-programmer number; see Section 7.2.3. 


The project number can be between 1 and 254; the 
programmer number can be between 0 and 254. 


9-12 Password in Radix-50 format; see Section 7.2.4.1 
for a description of converting a string to 
Radix-50 format. 


13-14 Disk Quota. See Section 7.2.3 for a description 
of unsigned numbers. Zero means unlimited quota. 
15-22 Not used 
23-24+ Device name 
25+ Unit number 
26+ Unit number flag 
27-28 User file directory (ufd) cluster size; 0 means 


use the pack cluster size. 


29-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


ILLEGAL FILE NAME 2 
Password is missing in the call 


NO ROOM FOR USER ON DEVICE 4 
The directory currently has the maximum 
number of accounts. 


PROTECTION VIOLATION 10 
The project-programmer number is [0,0] or 
either the project or programmer number 
is 255. 
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NAME OR ACCOUNT NOW EXISTS 16 
The account specified in the call currently 
exists on the device specified. 


ILLEGAL CLUSTER SIZE 23 
The cluster size specified in the call 
is either greater than 16 or is non-zero 
and less than the pack cluster size. 
See Section 5.4.3 for a discussion 
of valid cluster size values. 
DEVICE NOT FILE STRUCTURED 30 


The device specified is not a disk 
or the disk is open in non-file 
structured mode. 


Discussion: 


This call is used by the REACT system program to create accounts. 
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7.2.7.2 Delete User Account - Privileged (FQ0=1) 


Data Passed: 


Byte (s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHRS(1%), the delete user account code 
3-6 Not used 
7-8 Project-programmer number. This call generates an 
error if account [0,0], [0,1], or [1,1] is 
specified. See Section 7.2.3 for an explanation 
of the value of each byte. 
9-22 Not used 
23-24+ Device name; must be a disk 
25+ Unit number 
26+ Unit number flag 
27-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


ACCOUNT OR DEVICE IN USE 3 
The account contains files (it has not 
been zeroed) or a user is currently 
logged into the system under the 
account. 


CAN'T FIND FILE OR ACCOUNT 5 
The account specified does not exist. 


PROTECTION VIOLATION 10 
Account specified is either [0,0], [0,1], 
or [l,l]. 


DEVICE NOT FILE STRUCTURED 30 
Device specified is not a disk or is a 
disk open in non-file structured mode. 
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Discussion: 


The REACT system program uses this call to delete user accounts. To 
prevent error number 3, the user must first zero the account using 
either the /ZE option in the PIP system program or the ZERO command of 
the UTILTY system program. The FIP call (F0=13) can also zero an 
account, 
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7.2.8 Set Terminal Characteristics Privileged (F0=16) 


Data Passed: 
Byte(s) 

1 

2 


Meaning 
CHRS (6%), the SYS call to FIP 


CHRS$ (16%), the set terminal characteristics code; 
if CHR$(3%), byte 3 must be odd. 


If byte 2 is CHR$(3%), this byte must be CHRS$(N%) 
where N% is an odd value. 


CHRS(N%) where N% is 255% for the current keyboard 
or is the keyboard number of the terminal to 
alter. 


CHRS$(N%) where N% is 0% for no change or is the 
terminal width plus 1. The call sets the number 
of characters per line to N-l where N% can be 
between 2 and 255. The WIDTH n command sets this 
byte. 


CHRS(N%) where N% is: 
0 for no change 
128 to enable hardware horizontal tab feature. 
The TAB command sets this characteristic. 
(Device must have the requisite hardware.) 
255 to enable software horizontal tab 
positions which are set every 8 character 
positions, beginning at position 1l. The 
NO TAB command sets this characteristic. 


CHRS(N%) where N% is: 

0 for no change 

128 to enable the software to perform form 
feed and vertical tab operations by 
executing four line feed operations. The 
NO FORM command sets this characteristic. 

255 to enable hardware form feed and vertical 
tab. The FORM command sets this 
characteristic. 


CHRS (N%) where N% is: 

0 for no change 

128 to allow terminal to receive and print 
lower case alphabetic characters. The LC 
OUTPUT command sets this characteristic. 

255 to have the system translate lower case 
alphabetic characters to upper case before 
transmitting to a terminal. The NO LC 
OUTPUT sets this characteristic. 


SYS SYSTEM FUNCTION CALLS AND THE PEEK FUNCTION 


9 CHRS$(N%) where N% iss: 
0 for no change 

128 to have terminal not respond to XON 

CHRS (17) and xXOFF CHRS(19}) characters 

because it lacks the reguisite hardware. 

The NO XON command sets this 


255 


10 CHRS (N&) 


0 
128 


255 


characteristic. 

Terminal has requisite hardware to respond 
to XON and xXOFF characters. Terminal 
stops sending characters when it receives 
a CHR$(19) character (XOFF) and resumes 
sending characters when it receives a 
CHR$(17) character (XON). The XON command 
sets this characteristic. 


where N% is: 

for no change 

to have characters typed at the terminal 
sent to the computer only. The computer 
echoes (transmits back to the terminal) 
what it receives and performs any 
necessary translation. The FULL DUPLEX 
command sets this characteristic. 

to have the terminal (or its acoustic 
coupler) locally echo the characters 
typed. The computer does not echo the 
characters received. The LOCAL ECHO 
command sets this characteristic. 


ll Sr ie where N% is: 


Be 


255 


for no change 

Terminal does not have features of a video 
display terminal. The NO SCOPE command 
sets this characteristic. 

Terminal is a video display, or cathode 
ray tube (CRT) type, and uses’ the 
following features: 


a. Responds to synchronization standard 
described by byte 17. 


b. The system executes a DEL character 
(RUBOUT) by sending a backspace, a 
space, and a backspace to the 
terminal. 


c. Any location on the screen can be 
addressed by direct cursor placement. 


The SCOPE command sets this 
characteristic. 
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12 CHRS (N%) 
0 
128 


255 


13 CHR§ (N8) 
0 
n 


255 


14 CHR$ (N%) 
0 
n 


255 


15 CHRS (N&) 
0 
1 


2 


where N% is: 

for no change 
System treats certain characters received 
as follows: 


a. Translate CHRS$(125) and CHRS$(126) into 
the ESC character CHR$(27). 


b. Translate lower case characters to 
upper case characters. 


Set by NO LC INPUT command. 

Terminal transmits the full ASCII 
character set and system treats special 
characters as follows: 


a. Treat only CHR$(27) as an escape 
character (echoed as the $ character 
and handled as a line terminating 
character). 


jon 
J 
a] 
ID 
yp 
= 
(2) 
an 
pe) 
Uy 
~ 
font 
N 
wm 
~ 


Treat CHRS§ and CHRS (126) as 
printed characters and 


c. Do not translate lower case characters 
to upper case format. 


Set by LC INPUT command. 


where N% is: 

for no change 

Set fill factor of terminal to N%-l. The 
command FILL n determines this value. 

Set fill factor for an LA30S_ (serial) 
DECwriter. The command FILL LA30S sets 
this characteristic. 


where N% is: 

for no change 

The internal speed value to determine’ the 
baud rate at which the terminal receives 
characters. If byte 16 is 0, this value 
also determines the transmit (output) baud 
rate. If byte 16 is 255, this byte must 
be 255. For a DH11 line, n is between l 
and 16. For a DCll line, n is between 1 
and 4, See the PDP-1l Peripherals 
Handbook for the related baud rates. 
2741-type terminal. Byte 16 must also be 
255%. 


where N% is: 

for no change 

Do not set the output parity bit. This 
value is set by the NO PARITY command. 

Set the output parity bit for even parity 
format. The EVEN PARITY command sets this 
value. 

Generate an output parity bit for odd 
parity format. The ODD PARITY command 
sets this value. 
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16 CHRS(N%) where N$% is: 
0 Both the receive (input) and transmit 
(output) speeds are determined by n in 
byte 14. 
n The internal speed value to determine the 


baud rate at which the terminal transmits 
characters when a split speed setting is 
used. For a DH1l line, n is between 1 and 
16; for a DC1l line, n is between 1 and 
4. 

255 2741-type terminal. (See description of 
byte 20.) Byte 14 must also be 2558. 


17 iN’) where N% is: 
for no change 

16 Terminal ignores synchronization standards 
described for 255% value. The NO STALL 
command sets this characteristic. 

255 Terminal obeys the synchronization 
standard as follows. The computer stops 
sending characters if the terminal 
transmits a CHRS$(19) character (XOFF, or 
the CTRL/S combination). Computer resumes 
sending characters when the terminal 
transmits a CHRS$(17) character (XON, or 
the CTRL/Q combination). The STALL 
command sets this characteristic. 


18 CHRS(N%) where N% is: 
0 for no change 
128 System echo prints a control character 
received as the up arrow (*~ or ) character 
followed by the equivalent printable 
character. For example, the CTRL/D 
combination is printed as “D, CHRS$(94) 
followed by CHRS$(68). The UPARROW command 
sets this characteristic. 
255 System treats control characters as such. 
The NO UPARROW command sets this 
ta 


19 CHRS$(N%) where N% is a value between 1 and 30 and 
determines the maximum number of characters in a 
burst for a DH11 line. For low speed lines, this 
is set to 30; for VT50 lines, it is set to 12. 
The DH BURST n command sets this value. 


20 CHR$(N%) where N% depends on the values of two 
other bytes. If bytes 14 and 16 are both 255, the 
value of this byte applies to the 2741-type 
terminal as follows: 


n = 8 + DATA+STOP+PARITY 


21 


22 
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where: 


DATA is O for 


STOP is O for 


5 bits per character 
1 for 6 bits per character 
2 for 7 bits per character 
3 for 8 bits per character 


1 stop bit per character 
4 for 2 stop bits per character 
or 1.5 bits if DATA=0. 


PARITY is 0 for no parity bit. 


16 for even parity format 
48 for odd parity format. 


If either byte 14 or 16 is other than 255, this 
byte is not used. The 2741 command determines the 
value of this byte. 


CHRS (N%) where N% is: 


0 
255 


for no change 

Set the ring list entry for a terminal 
attached to a DCll, DLI1E or DH11 line 
interface to default to permanent 
characteristics when modem is answered. 
The /RING option with a MTTYSET KBn: 
command determines this value. 


ARAN) where N% is: 


128 


255 


for no change 

The system software treats an incoming ESC 
CHR$ (27%) character as a line terminating 
character and echoes it as the $ 
character. The NO ESC SEQ command sets 
this value. 

The software treats an incoming ESC 
CHR$(27%) character and the next incoming 
character as a special escape sequence. 
The software does not echo either 
character but transposes the characters 
and changes the ESC character to a 
CHRS$ (155%) character. That is, if the 
incoming data is: 


then the user receives: 


X ESCAPE 
XXX 155 


The ESC SEQ command sets this value. 
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Data Returned: No meaningful data is returned. 


Possibie Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
The keyboard number specified in byte 4 
of the call is out of range of the valid 
keyboard numbers. 


Discussion: 


If the terminal specified by the keyboard number in byte 4 of the call 
either is disabled (as a result of the system initialization procedure 
or of executing the disable terminal SYS call) or is a_ pseudo 
keyboard, the call is not executed by the system. 


The TTYSET system program employs this call to set terminal 
characteristics. Refer to the discussion of TTYSET in Section 4.5 of 


the RSTS-11 System User's Guide. 
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7.2.9 Change File Statistics 
Privileged FQ=-11) 


Data Passed: 


Byte(s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHRS$ (-11%), change file statistics code 
3 CHRS(N%) where N% is the internal channel on which 
the file is open. Must be between 1 and 12, 
inclusive 
4-5 Desired date of last access 
6-7 Desired date of creation 
8-9 Desired time of creation 
10-30 Not used 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
The file open on the channel specified 
is not a disk file or is a user file 
directory. An attempt by a non-privileged 
user to execute this call. 


Discussion: 


The data passed by this call replaces the related data in the 
accounting block of the file open on the channel specified in byte 3. 
No error checking is done on the date and time values passed. Since 
the call does not supply default values, the user program must supply 
all three date and time values each time the call executes. The call 
is used by the BACKDK system program to maintain original date and 
time statistics for a file. 
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The following is a partial directory listing of a privileged account 
showing the file whose statistic information is to be changed. 


ror 
onl 


CTPELD. BAS é 66 @4-SEFP-74 @Z-MAY-74 @9:Ge PM 


The following program changes the date of creation to 22-July-74, and 
the date and time of last access to 12:00 noon, 22-July-74, as shown 
on the partial directory listing following the program. 


LISTNH 

18 OPEN "CTPBLD. BAS" AS FILE 1% | OPEN FILE TO CHANGE 

26 DIM Mu<zax? ' USE THIS ARRAS TO SET UP CALL 

x8 2 Ae 

4a MecAH 

58 Mucon oe 1 SET UP FOR CHANGE STATS CALL 

ra Mec RH =Le ! CN CHANNEL 4. 

7a MZCdk=42G38 AND 255% 

MCSE SSHAPH (420220) AND 25S! SET UF DATE CF CREATION 

1 FOR 22-JUL-74 (DATES¢420EH)= 
!  BE-JUL-74) 

8G MEC68I=42632 AND Z55u 

> MECPROSSNAPHC42022) AND 255%  ! SET UP LAST ACCESS TO 22-JUL-74, 
30 MEC8xI=720% AND 255% 
MECORISSWAPACP 202) AND 255% 9 SET UP TIME OF LAST ACCESS To 12 

1 <TIMES(72Gn3=42-08 PMD 

iae CHANGE MX TO M¢ ' SET IT UF AS Fl STRING 

110 M$=SYSCM#? ! AND DC THE WORK 

22767 END 

READY 

RUNNH 

READY 

CAT 

CTPBLD. BAS 2 6a #E-JUL-74 Z2-JUL-74 12:00 PH 

READY 


MO 
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7.2.10 LOGIN And LOGOUT SYS Calls 


7.2.10.1 LOGIN - Privileged (F0=4) 


Data Passed: 


Byte(s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHRS (4%), the LOGIN code 
3-6 Not used 
7-8 Project-programmer number. Must not be = account 


[0,1]. See Section 7.2.3 for an explanation of 
the value of each byte. 


9-12 Password in Radix-50 format. See Section 7.2.4.1 
for a description of converting a string to 
Radix-50 format. 


13-30 Not used. 


Data Returned: 
Byte(s) Meaning 
1-2 Internal data 


3 Total number of jobs logged into the system under 
this account 


4-? Job numbers of each job running detached under 
this account. A byte of CHR$(0%) signifies the 
end of the list. Only the first 26 job numbers 
are returned. 


Possible Errors: 
Meaning ERR Value 


CAN'T FIND FILE OR ACCOUNT 5 
The project-programmer number specified 
in the call is [0,1], does not exist, or 
its password does not match the password of 
the account on the system. 
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Discussion: 


If the calling job is already logged into the system, this call 
not change the job's account. The data returned in bytes 3 thro 


doe 
h 3 
refers to the same account under which the job is running. 


ug 


7-73 
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7.2.10.2 LOGOUT - Privileged (F0=5) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS (5%), the LOGOUT code 
3-30 Not used 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


ILLEGAL SYS(} USAGE i8 
The JFHIBY value is not set when the 
call is executed. 


Discussion: 


This call closes all open channels, deassigns all devices, updates 
statistics on the disk, clears the job from the monitor message table 
and disassociates the project-programmer number from the job number. 
However, none of these actions are performed unless the monitor sets a 
special flag called JFHIBY. 


The monitor sets JFHIBY only when a user types the HELLO, BYE or 
ATTACH commands at a terminal logged into the system or types anything 
at a terminal not logged into the system. No way exists for a 
BASIC-PLUS program to set JFHIBY. Thus, an already running program 
can never log itself off the system. 


When the monitor sets the JFHIBY flag, the running program has full 
privileges. The drop temporary privileges call resets the JFHIBY flag 
to disable the privileges afforded by the flag. The LOGOUT and LOGIN 
system programs use the logout call. 
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7.2.11 Detach, Attach, And Reattach SYS Calls 


7.2.11.1 Detach - Privileged (F0=7) 


Data Passed: 


Byte(s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHR$(7%), the detach code 
3-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
The current job is already detached or 
its console keyboard is open on a channel 
other than channel 0. 


Discussion: 


This call disassociates the job and its console keyboard. The 


following sample program segment prints a message and detaches from 
the keyboard. 


100 PRINT "DETACHING..." 
! NOTIFY THE USER 

110 A$ = SYS(CHR$(6%) + CHR$(7$%)) 
! DO THE DETACH 


When data is entered at a RSTS/E terminal, the system activates a job 
to handle the input and gives the job the next available job number. 
If the data is recognized by the System, certain actions are executed 
under that job number, one of which can be logging a user into the 
System. (See Sections 2.1 and 4.1 of the RSTS-11 5 stem User's Guide 
for the operational details.) When a user is logged into the system, 
the activated job is associated by the system with both the terminal 
at which he is typing and the account number which he used to identify 
himself to the system. The job is then considered active on the 
system and in attached mode, or, simply, attached to the terminal. 
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A privileged job can become detached from the terminal by executing 
this call. Once a job is placed in the detached state, it runs as any 
other job logged into the system but it does not employ a terminal 
device on channel 0. The detached state is advantageous for 
non-interactive jobs. The job running detached frees a terminal for 
other usage and makes the job immune from interruption by someone 
typing a CTRL/C combination. 


When the user desires to attach a detached job to a terminal, he can 
log into the system at any free terminal using the account number 
under which the detached job was made active and attach that job to 
the terminal. (This procedure is described in Section 4.1 of the 
RSTS-11 System User's Guide.) Since the system associated the job 
number of the attached job with the account number under which that 
job was made active, it reports the detached job under the same 
account number. 


This attachment facility is valuable in another manner. A job can be 
placed in a detached state by the system when the carrier is dropped 
on a remote line. This means that, if the telephone connection is 
lost while a job is running from a terminal at a remote location, the 
content of the job is not lost. The user simply logs into the system 
again with the same account number and reattaches to the job he was 
previously running. 


The ERRCPY, QUEMAN, SPOOL, and BACKUP system programs use this call. 
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7.2.11.2 Attach - Privileged (F0=6) 


Data Passed: 
Byte (s) 

1 

2 


7-10 


11-30 


Data Returned: 


Meaning 
CHRS$ (6%), the SYS call to FIP 


CHRS$ (6%), the attach and reattach code. The 


code 


to attach and reattach is the same but the format 


of the data passed is quite different. 
Section 7.2.11.3 for the reattach format. 


See 


The number of the job to attach to the terminal. 


Must be 0 


Project-programmer number of the job to attach 


to 


the terminal. See Section 7.2.3 for a description 


of the exact contents of each byte. 


Password of the account specified in bytes 5 and 6 


in Radix-50 format. See Section 7.2.4.1 


for 


information on converting a string to Radix-50 


format. 


Not used. 


No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 
Each of the following conditions 
generates this error: 


1. 


2. 


3. 


The job executing the call has an open channel. 


The job executing the call is a source (BAS) 
program rather than a compiled (BAC) program. 


The job number specified in byte 3 is not a 
detached job. 


The account or password in the call is not valid. 


The job executing the call is detached. 
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Discussion: 


The LOGIN system program is the only program that can execute 
call. See the LOGIN.BAS listing for an example of its usage. 
that, if byte 3 is the number of the job executing the call, 


this 
Note 
the 


system performs the reattach action. See Section 7.2.11.3 for a 


description of the reattach process. 
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7.2.11.3 Reattach - Privileged (F0=6) 


Data Passed: 


Byte(s) Meaning 

1 CHRS (6%), the SYS call to FIP 

2 CHRS$ (6%), the attach and reattach code. The code 
to attach and reattach is the same but the format 
of the data passed is quite different. See 
Section 7.2.11.2 for the attach format 

3 CHR$(J%) where J% is the number of the job 
executing the call 

4 CHRS$(K%) where K% is the keyboard number of the 
terminal to which the calling job is to be 
attached 

5-30 Not used 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


ILLEGAL SYS({) USAGE 18 
Each of the following conditions generates 
this error: 


1. The job number specified in byte 3 is less than 1 
or greater than the JOB MAX value on the system. 
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3. The keyboard number in byte 4 is out of range. 

4. The terminal specified by the keyboard number in 
byte 4 is currently assigned, opened, or the 
console keyboard of some job. 


5. The job executing the call has an open file. 


6. The job executing the call is a source’ (BAS) 
program rather than a compiled (BAC) program. 
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Discussion: 


A privileged job can execute this form of the attach and reattach 
call. The call establishes the terminal specified in byte 4 as the 
console keyboard of the detached job executing the call. In this 
manner, a job can reattach to a terminal without having to force the 
proper data to the desired terminal. 
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7.2.12 Send And Receive Messages 
Both Privileged (F0=18) and Not Privileged 

This function call allows a user's job to do the following: 

a. declare itself a receiving job, 

b. send a message to a receiving job, 

c. receive a message from pending messages, 

d. stall until a message is pending, and 

e. eliminate itself or another job as a receiving job. 


The monitor controls eligibility to receive messages by maintaining a 
table of receiving jobs. The response to the RECEIVERS guery at 
system generation time determines the maximum number of jobs eligible 
to receive messages at any given time. To be eligible to receive 
messages, a job must declare itself and have its identification 
entered in the table of receiving jobs. A job sending a message 
succeeds only if the job to which the message is sent has an entry in 
the table. 


Sending and receiving messages on the system uses small buffers. Each 
message occupies one small buffer. A job defines, in its first 
receive call, the number of pending messages (messages sent to the job 
but not yet received by the job) which monitor allows to be queued for 
the job at any given time. This maximum can be as high as 127. To 
prevent occupying a large number of small buffers, and thereby 
degrading system performance, the pending maximum for each receiver 
should be small (10 to 15) and each receiving job should extract its 
messages quickly. 


The system controls message operations on a first-in, first-out (FIFO) 
basis. It maintains pending messages as a linked chain of small 
buffers. When a job sends a message to an eligible receiving job, the 
system appends the related small buffer to the last small buffer in 
the chain of messages pending for the job. When a receiving job asks 
for a pending message, the system makes available the first message in 
the chain and removes the related small buffer from the chain. 


The system continues message operations for a receiving job until 
either the maximum number of messages are pending or the supply of 
small buffers is exhausted. Since such conditions affect system 
operations, a receiving job must process its pending messages 
frequently to maintain adequate system performance. Since poorly 
designed use of the receive mechanism can drastically degrade overall 
system performance, the receive operation can be executed only by a 
privileged user. 


A receiving job must remove itself from the table of receiving jobs or 
have another job remove it. To keep non-active jobs from occupying 
entries in the table of receivers, both the logout SYS call and _ the 
kill job SYS call remove the job from the table of eligible receiving 
jobs. 


SYS SYSTEM FUNCTION CALLS AND THE PEEK FUNCTION 


7.2.12.1 Declaring A Receiver And Receiving A Message - Privileged 


(FO=18) 
Data Passed: 
Byte(s) 
1 


2 


5-8 


9-30 


Meaning 
CHRS (6%), the SYS call to FIP 
CHRS$ (18%), the send and receive a message code 
CHRS(N%) where N% is one of the following values: 


1 Attempt to receive a message or declare this 
job as a receiver and attempt to receive a 
message. Return an error condition if no 
messages are pending. 


2 Receive with sleep. Similar to 1 except that 
the job executes a sleep operation if no 
messages are pending. This action occurs in 
place of generating an error condition. 


CHRS (P$+L%) where P% can be either 0 or 128. If PB 
is 0, messages can be received from any sending 
job. If P is 128, messages can be received from 
and queued only by sending jobs which are 
privileged. 


L$ is the number of messages (between 1 and 127) 
which can be simultaneously pending for this 
receiving job. 


Receiving job logical name in Radix-50 format. 
See Section 7.2.4.1 for a description of 
converting a string to Radix-50 format. 


Not used. 
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Data Returned: 


Byte(s) Meaning 
1-4 Not used 
5 CHR$(J%) where J% is the job number times 2 of job 
sending the message 
6 Must be CHRS(0$%) 
7-8 Project-programmer number of the pending job. See 


Section 7.2.3 for a description of each byte. 


9-28 The message string. The system pads any unused 
bytes with NUL characters to a length of 20 bytes. 


29-30 Not used. 


Possible Errors: 
Meaning ERR Value 


NO ROOM FOR USER ON DEVICE 4 
When the job attempts to declare itself 
as a receiving job, the monitor table 
containing data of eligible receiving 
jobs is full or is zero length. 


CAN'T FIND FILE OR ACCOUNT 5 
For receive only, error indicates no 
messages are pending. For receive with 
sleep, error indicates no messages were 
pending when the receive was executed by 
monitor. Error is returned to the program 
when monitor awakens job from sleep. 
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when the Job “at tenipee to declare itself 
as a receiving job, either the logical 
name is missing from the call (bytes 5 
through 8 are not given) or another job 
has already declared itself a receiver 
with the logical name given. 
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Discussion: 


A receive call checks the eligibility of a job to receive messages and 
performs both or one of two actions based on the result of the check. 
First, if the job is not eligible to receive messages, the call 
declares the job as an eligible receiver and attempts to receive a 
message. Second, if the job is already eligible, the call attempts to 
receive a message. Since the same call performs two actions, it is 
important that the user program handle the declaration and receiving 
procedure properly. 


To check the eligibility of a job to receive messages, the system 
determines if the calling job's job number appears in a table in the 
monitor part of memory. If the job number is not in the so_ called 
receiver table, the system ensures that the logical name specified in 
bytes 5 through 8 of the data passed is not currently being used by 
another job. If the logical name is unique and an empty slot is 
available, the system declares the job as a receiver by entering in 
the table its job number, its logical name, and other data. 
Subsequent to declaring the job as a receiver, the receive call never 
refers to the logical name. The logical name exists so that a sending 
job can easily refer to a receiver without supplying its job number. 


A receive call can not change a logical name in the table of eligible 
receivers because the system refers to the job number in the receive 
table rather than to the logical name. If the job number of the 
current job is in the table, the system considers the job eligible and 
has no need to refer to the logical name. This condition is important 
if a previous receiver with the same job number as the current 
receiver failed to remove itself from the table before terminating 
processing. Thus, a logical name already appears in the table for the 
current receiver when it attempts to declare itself a receiver. 


To eliminate the possibility of a spurious logical name appearing in 
the table for the current job, it is recommended that a program 
execute the call to remove itself as a receiver before it executes the 
first receive call to declare itself a receiver. In this manner, the 
program ensures that the logical name in the table for the current job 
is, in fact, the name declared in bytes 5 through 8 of the call. 


When the receive call declares a job as a receiver, it also attempts 
to receive a message. Because the system does not queue messages for 
a job which is not an eligible receiver, the first attempt to receive 
a message always fails. 


When the receive call determines that a job is eligible, it attempts 
to receive amessage. If a message is pending for the job, the call 
returns the information in bytes 9 through 28 of the target string. 
If no message is pending for the job, the call executes according to 
the value of N% in byte 3 of the data passed. If the value of N% is 
1, the call immediately generates a recoverable error (ERR = 5). If 
the value of N% is 2, the call puts the job in a SLEEP state (called a 
receiver sleep). 


The system awakens a job in a receiver sleep if a message becomes 
queued for it or if a line terminating character is typed on one of 
its keyboards. Since the system presets the recoverable error 
condition (ERR = 5) before putting the job to sleep, the receiving 
job, upon awakening, detects the error condition. The system does not 
pass the message to the job. To obtain the message queued, the job 
must execute the receive call again. 
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7.2.12.2 Send A Message - Both Privileged and Not Privileged (F0=18) 


Data Passed: 
Byte (s) 

1 

2 


Data Returned: 


Meaning 
CHRS$ (6%), the SYS call to FIP 
CHR$ (18%), the send and receive a message code 


CHRS$S(-1%); this value indicates that the call is 
a request to send a message 


CHR$(J%) where J% is the job number times 2 of the 
job to receive the message. If J% is 0, the call 
uses the logical name in bytes 5 through 8 to 
determine the receiving job 


Receiving job name in Radix~-50 format. See 
Section 7.2.4.1 for a description of converting a 
string to Radix-50 format. 


Message text to send. Can be a maximum of 20 
bytes and the system pads the message with NUL 
characters to the length of 20 bytes 


Not used. 


No meaningful data is returned. 
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Possible Errors: 
Meaning ERR Value 


CAN'T FIND FILE OR ACCOUNT 5 
The receiving job specified is not in 
the monitor table of eligible receiving 
jobs. 


ILLEGAL SYS() USAGE 18 
The receiving job specified is capable 
of receiving messages only from 
privileged jobs and the sending job is 
not privileged. 


NO ROOM AVAILABLE FOR FCB 32 
One of two conditions is possible. 


1. The number of messages pending for 
the receiving job is at its declared 
maximum. The sending job must try 
again. If this condition occurs 
frequently, it indicates that the 
declared maximum is too low or that the 
receiving job is not processing its 
messages quickly enough. 


2. Also, sending a message requires a 
small buffer and one is not available. 


Discussion: 


The SEND operation sends a message to a declared receiving job in one 
of two ways: by either a job number or by a job identification. When 
byte 4 of the data passed is non-zero, the call ignores bytes 5 
through 8 and attempts to send the message to the job designated by 
the value in byte 4. If byte 4 is zero, the call attempts to send the 
message to the receiver whose identification matches that given in 
bytes 5 through 8. 


The sending job can be either privileged or non-privileged. The 
sending job must be privileged if the receiver is capable of receiving 
messages only from privileged sending jobs. (The receiver determines 
this capability by specifying a proper value in byte 4 of the Declare 
a Receiver SYS call.) If a non-privileged sender attempts to send a 
message to a receiver which is accepting messages only from privileged 
sending jobs, the monitor does not queue the message and returns’ the 
ILLEGAL SYS() USAGE error to the non-privileged sender. The sending 
job can be either privileged or non-privileged if the receiver is 
capable of receiving messages from any sending job. 
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7.2.12.3 Removing A Receiver - Privileged (F0=18) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$ (18%), the send and receive a message code 
3 CHR$(0%) to remove a receiving job from the 


monitor table of receiving jobs 


4 CHRS$(N%) where N% is the number of the job to 
remove or is 0Q to remove the job executing the 
call 

5-30 Not used, 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 
ILLEGAL SYS() USAGE 18 


An attempt by a non-privileged job to 
execute this call. 


Discussion: 


This function removes the job number and logical name from the receive 
table. All pending messages are lost. 
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7.2.13 Poke Core Privileged (F0=-6) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS(-6%), the poke core code 
5-6 CHRS (A%) +CHRS (SWAP%(A%)) where A% is the address 
to change 


CHRS (V%) +CHRS (SWAP%(V%)) where V% is the value to 
insert at the address specified by bytes 3 and 4. 


7-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 


PROTECTION VIOLATION 10 
The job executing the call is not 
operating under account [1,1] or the 
address specified in the call is an 
odd value. 


Discussion: 


This call changes a word in the monitor part of memory to the value 
the user specifies. Obviously, this is a very dangerous capability, 
and it is, therefore, heavily protected. It can only be called from a 
job running on account [1,1]. 


The poke call allows only full word changes. If the user desires a 
byte change, he must read the word (using the PEEK function), change 
the desired byte, and rewrite (using the POKE call) the entire word. 
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7.2.14 Set Logins Privileged (F0=-19) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$(-19%), the set logins code 
3 CHRS(N%) where N% is the number of logged in jobs 
to allow 
4-30 Not used 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged job to 
execute this call. 


Discussion: 


This function sets the number of allowable logins to the number 
Specified in byte 3. If N is 0, the number set is l. If N is greater 
than the system JOBMAX set at start up time, then the number set is 
the value of JOBMAX. 
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7.2.15 Accounting Information 


7.2.15.1 Read Or Read And Reset Accounting Data - 
Both Privileged and Not Privileged (F0=14) 


Data Passed: 


Byte(s) 


5-6 


7-8 


Meaning 
CHRS (6%), the SYS call to FIP 


CHRS$ (14%), the read or read and reset accounting 
data code 


CHRS (N%) +CHRS$ (SWAP%(N%)) where N% is the index 
number of the account to read. If N% is 0, read 
the account specified in bytes 7 and 8. 


CHRS(N%) where N% is 0 to indicate read only and 
is non-zero to indicate read and reset. If the 
job executing this call is not privileged, the 
system does not access this word and performs only 
a read operation. 


Project-programmer number. Used only if bytes 3 
and 4 are 0. See Section 7.2.3 for a description 
of each byte. 

Not used 


Device name; must be a disk. A zero in both 
bytes indicates the system disk. 


Unit number 
Unit number flag 


Not used 
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Data Returned: 


Byte(s) Meaning 

1-4 Internal coding 

5-6 Number of blocks owned by the account read 

7-8 Project~programmer number of the account read 

9-12 Password of the account read; in Radix~50 format 

13-14 Low order word (16 bits) of the CPU time (in 
tenths of seconds) used by the account 

15-16 Connect time (in minutes) used by the account 

17-18 Low order word (16 bits) of kilo-core ticks used 
by the account 

19-20 Device time (in minutes) used by the account 

21-22 High order bits for CPU time and kilo-core ticks. 
See the discussion for an explanation of how the 
values are stored. 

23-26 Device and unit information unchanged 

27-28 Disk quota in number of blocks; 0 means unlimited 
quota 

29-30 User file directory cluster size. 


Possible Errors: 


Meaning ERR Value 
CAN'T FIND FILE OR ACCOUNT 5 
The project-programmer number specified 
does not exist on the disk or the index 
specified is greater than the number of 
accounts on the disk. 
ILLEGAL SYS({) USAGE 18 


Device specified is not a disk. 


Discussion: 


This FIP call is the only one provided in RSTS/E to lookup accounts on 


a disk. By starting the index (bytes 


3 and 4) at 1 and incrementing 


it for each call, the user program can retrieve the project-programmer 


number of every account on the disk. 
System program (Section 6.5) for a 
information. 


See the description of the MONEY 
discussion 


of the accounting 
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The word returned in bytes 21 and 22 holds the high order bits of CPU 
time and kilo-core ticks. The bottom ten bits of this word apply to 
kilo-core ticks, and the top six bits apply to CPU time. Graphically, 
the word looks like the following: 


bit 15 1g 2 g 


High Order Part High Order Part 
of CPU Time of KCT 


If a non-privileged program executes this call, the system forces the 
following bytes in the data passed to the values shown. 


3 and 4 0 Look up the account 
specified in bytes 
7 and 8 
5 and 6 0 Read only 
7 and 8 current Look up data for 
PPN current project- 


programmer number 


If a privileged program executes this call and bytes 5 and 6 of the 
data passed are non-zero, the following account information is read 
and reset to zero. 


CPU time 
kilo-core ticks 
connect time 
device time 
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7.2.15.2 Accounting Dump - Privileged (F0=-15) 


Data Passed: 


Byte(s) Meaning 
1 CHR$ (6%), the SYS call to FIP 
2 CHRS (-153%), the accounting dump code 3-4 
Project-programmer number of the account to which 
the system dumps the accumulated usage data. See 


Section 7.2.3 for a description of each byte. 


If both bytes are zero, the data is dumped to the 
current account. 


5-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


CAN'T FIND FILE OR ACCOUNT 
The account specified in bytes 3 and 
4 does not exist. 


Discussion: 


This function allows a program to dump accumulated accounting data to 
the account specified in bytes 5 and 6. This capability enables user 
callable utility programs to run on an account different from the 
account which called them and still charge the calling account for the 
time accumulated by the utility. For example, the SPOOL program must 
run on a privileged account, but is callable by non-privileged users 
through the QUE command. It is desirable that the calling user be 
charged for the time the SPOOL program accumulates processing the job. 
The SPOOL program could take advantage of this SYS call to effect this 
process. (1) 


(1)The version of SPOOL released with RSTS/E does not perform this 
function. 
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7.2.16 Directory Look Up 
The SYS function calls described in this section look up file names 
under programmed control. Although only two codes are available, four 
different types of operation are possible. As a result, four 
descriptions appear in this section. 


The four types of operation return the data in the same format as 
described below. 


Data Returned: 


Byte(s) Meaning» 
1-4 Not used 
5-6 Same as data passed. (Project-programmer number) 
7-10 File name in Radix-50 format. See Section 7.2.2 


for a description of converting a string in 
Radix-50 format 


11-12 Extension in Radix-50 format 
13-14 Length in blocks or _ sectors. (Not used for 
special magtape look up described in Section 
7.2.16.2) 
15 Protection code of the file 
16 0 
17-18 For disk, the date of last access; for tape, the 
date of creation 
19-20 For disk, the date of creation; for tape, not 
used 
21-22 For disk, the time of creation; for magtape, the 


project-programmer number of the file 


23-26 Same as data passed. (Device name, unit number, 
and flag byte) 


27-28 For disk, the file cluster size; for tape, not 
used 
29 Number of entries returned: for disk, 8; for 


tape, 6. (Not returned if FO is 17.) 


30 Not used. 
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7.2.16.1 Directory Look Up On Index - Not Privileged (F0=15) 


Data Passed: 


Byte(s) 


27-30 


Data Returned: 


Meaning 
CHRS$ (6%), the SYS call to FIP 
CHRS$ (15%), the directory look up on index code 


CHRS (N%) +CHRS (SWAP% (N%)) where N% is the index of 
the file to read. If N% is 0, return the data for 
the first file in the directory. If NS is x, 
return the data for the x+l file in the directory. 
On magtape, N% must be 0 to rewind the tape before 
reading the first file. See Section 7.2.16.2 for 
a description of magtape operations. On DECtape, 
N% must be 0 to read the directory blocks from the 
tape before reading the first file. Subsequent 
calls where N% is not zero read the directory from 
the BUFF.SYS file. 


Project-programmer number of the directory to look 
up. If both bytes are 0 and the device specified 
in bytes 23 and 24 is magtape, the call returns 
information for each file read. If the device 
specified in bytes 23 and 24 is DECtape, the call 
does not use these bytes but returns information 
for each file read. See Section 7.2.3 for a 
description of these bytes. 


Not used 

Device name for look up 
Unit number 

Unit number flag 


Not used. 


See introductory material for Section 7.2.16. 
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Possible Errors: 
Meaning ERR Value 


CAN'T FIND FILE OR ACCOUNT 5 
The account specified does not exist 
on the device specified or no more 
files exist on the account (the index 
value is greater than the number of 
files on the account). 


DEVICE NOT FILE STRUCTURED 30 
The device specified in the call is 
not a file structured device. 


VARIOUS DEVICE DEPENDENT ERRORS 
The call also returns device dependent 
errors such as DEVICE HUNG and DISK 
PACK NOT MOUNTED. 


Discussion: 


The CATALOG system command employs the same routines as this call _ to 
print a directory listing. The ordering of the files in the listing 
is by index value from the lowest to the highest. The user can 
therefore determine the index value for a certain file by counting its 
position in a CATALOG listing and subtracting one. 


If the device specified is magtape, the monitor, after reading a file 
label, skips to the end of the file on the tape to determine the 
number of blocks in the file. 
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7.2.16.2 Special Magtape Directory Look Up - Not Privileged (F0=15) 


Data Passed: 


Byte (s) 


3-4 


Data Returned: 


Possible Errors: 


Meaning 
CHRS$ (6%), the SYS call to FIP 
CHRS$ (15%), the directory look up on index code 


CHRS (N%) +CHRS (SWAP%(N%)) where N% is the index of 
the file to read. If N% is 0, return the data for 
the first file in the directory. If N% is x, 
return the data for the x+l file in the directory. 
On magtape, N% must be 0 to rewind the tape before 
reading the first file. See Section 7.2.16.2 for 
a description of magtape operation. On DECtape, 
N% must be 0 to read the directory blocks from the 
tape before reading the first file. Subsequent 
calls where N% is not zero read the directory from 
the BUFF.SYS file. 


Both bytes are CHR$(255%) to execute the special 
magtape directory look up 


Not used 

MT 

Unit number 

Unit number flag 


Not used. 


See introductory material for Section 7.2.16. 


Meaning ERR Value 


CAN'T FIND FILE OR ACCOUNT 5 
No more files exist on the tape. 


DEVICE NOT FILE STRUCTURED 30 
The device specified in bytes 23 
and 24 is not file structured. 
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Discussion: 


The standard directory look up call (described in Section 7.2.16.1) 
executed on a magtape unit results in the following actions by the 
monitor: 


a. Reads one record from the tape (a label record). 


b. Spaces the tape forward to the next end of file record and 
calculates the number of records in the file. 


c. Returns the directory information if the account number of 
the file matches the one specified in the call or if both 
bytes in the account specification in the call are zero. 


When the monitor executes the action described in statement a, the 
tape must be positioned immediately before a label record. Otherwise, 
an error is generated or garbage information is returned. 


In an application program which must search a tape for a specific file 
and read each specific file found, the OPEN FOR INPUT statement 
necessitates a rewind operation. The OPEN FOR INPUT statement 
executed on a fiie structured magtape generaliy causes the following 
actions. 


a. Reads one record from the tape which must be a label record. 


b. If the read operation is successful, then opens the file and 
returns control to the user program. 


c. If the read operation is unsuccessful and this is the first 
label read, then rewinds the tape and executes the action 
described at a. 

d. If the logical end of tape is detected, returns an error. 


e. If the label read does not match, skips to the end of this 
file and executes the action at a. 


The required rewind operations consume time and are clearly unwanted. 
To avoid the rewind operations, the application program can execute 
the special magtape directory look up call and perform certain 
actions. By specifying bytes 5 and 6 both as CHR$(255%) in the call, 
the program causes the following actions by the monitor. 

a. Reads from the tape a record which must be a label record. 


b. Backspaces one record which leaves the tape in a position to 
read the label record again. 


c. Returns the directory information (except for file length) to 
the program. 
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To take advantage of this special action, the program can perform the 
following actions. 


a. Dete rom the information returned whether the file is 
th = 
i 


b. If the file is required, execute the OPEN FOR INPUT statement 
using the file name and requesting no rewind. The action 
executes without a rewind because the tape is positioned 
properly. If the file is not required, space the tape 
forward to the next end of file record (see Section 12.3.7 of 


the BASIC-PLUS Language Manual) before executing another 
call. 


c. After processing the required file, execute a CLOSE statement 
to position the tape at the end of file record and to be 
ready to execute another call. 


The special look up call returns directory information on each file 
read regardless of its account number. However, the OPEN FOR INPUT 
statement must specify the correct account number if the account 
number of the file does not correspond to the current account number. 
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7.2.16.3 Disk Directory Look Up By File Name - Not Privileged (F0=17) 
Data Passed: 
Byte(s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHRS$ (17%), the disk directory look up by file name 
and disk wildcard directory look up code. See 
Section 7.2.16.4 for a description of the latter 
call. 
3-4 Both bytes must be CHRS$ (255%) 
5-6 Project-programmer number of the file to look up. 


See Section 7.2.3 for a description of each byte. 


7-10 File name in Radix-50 format. See Section 7.2.4.1 


for a description of converting a 
Radix-50 format. 


li-i2 Extension in Radix-50 format 
13-22 Not used 
23-24+ Device name; must be disk 
25+ Unit number 
26+ Unit number flag 
27-30 Not used. 


string 


Data Returned: See introductory material for Section 7.2.16. 


Possible Errors: 
Meaning 
ILLEGAL FILE NAME 
File name in bytes 7 through 10 is 
missing. 
CAN'T FIND FILE OR ACCOUNT 
The device specified in bytes 23 and 


24 is not a disk or the file specified 
does not exist on the specified disk. 


Discussion: 


This call works only on disk files and returns’ information 
specified file. 
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ERR Value 


for 


2 


the 
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7.2.16.4 Disk Wild Card Directory Look Up - Not Privileged (F0Q=17) 


Data Passed: 


Byte(s) 


3-4 


7-10 


11-12 


Data Returned: 


Possible Errors: 


Same as that described in Section 7.2.16.3 except for 
the following data. 


Meaning 


CHRS (1%) + CHRS$ (SWAP$%(I%)). If I is 0, return 
the data for the first file which matches the wild 
card specification. If I% is x, return the data 
for the x +1 =file which matches the wild card 
specification. 


Radix-50 representation of a wild card file name 
specification where an * character can replace the 
file name or a? character can replace any 
character in the file name. Used with the 
extension in bytes 11 and 12 to create a wild card 
file specification. See Section 7.2.4.1 for a 
description of converting a string to Radix-50 
format. 


Radix-50 representation of a wild card extension 
Specification were an * character can replace the 
extension or a ? character can replace any 
character in the extension. Used with the file 
name in bytes 7 through 10 to create a wild card 
file specification. See Section 7.2.4.1 for a 
description of converting a string to Radix-50 
format. 


See Introductory material for Section 7.2.16. 


Meaning ERR Value 
ILLEGAL FILE NAME 2 
No file name appears in bytes 7 through 
10. 
CAN'T FIND FILE OR ACCOUNT 5 


The device specified in bytes 23 and 
24 is not a disk or no match exists for 
the index value given in bytes 3 and 4. 


DISK PACK IS LOCKED OUT 22 
The disk is in the locked state and 
the account under which the call is 
executed is not privileged. 
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Discussion: 


This call allows a program to supply a wild card specification and to 
increment an index value to gain directory information for all 
occurrences of files matching the wild card specification. The 
following are typical wild card specifications and their meanings. 


FILE??.* All files with FILE as the first four 
characters in the name and with any extension 
(including no extension) 


* BAS All files with BAS extensions 


* .BA? All files with BA as the first two characters 
in the extension 


The program supplies an index of 0 and executes the call. The system 
returns directory information for the first file which matches the 
wild card specification. The program can increment the index by 1 and 
execute the call again to gain directory information for second and 
subsequent matching occurrences of files. The system returns error 
number 5 to indicate no more matching occurrences exist in the 
account. The entire procedure relieves the program of the overhead 
required to translate each file name in the directory and to compare 
for a match. 
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7.2.16.5 General Guidelines For Usage Of Directory Look Up Calls - The 
following conditions apply to executing one of the directory look up 
calls described in Section 7.2.16. 


If a program specifies either DECtape or magtape, the monitor assigns 
the related unit to the calling job while the call executes. The unit 
remains assigned after the call completes. 


When a program repeatedly executes one of the calls on disk and 
increments the index for each repetition, the execution time increases 
for each successive call. The increase occurs because the monitor 
must read the file name blocks for indices numbered 0 through N-1 
before it reads the file name block for index number N. The process 
is the only one possible since the index value has no other 
relationship to the actual disk address of the file name block. 


When a program repeatedly executes one of the calls on a system disk 
Structure having multiple public disks, the increase in execution time 
related to the index value is more critical. Since the monitor has no 
means of determining how many files exist on each unit of a multiple 
public disk structure, it must read the file name blocks of each unit 
beginning at unit 0 until the Nth file is read. Therefore, on such a 
System, execution time can be decreased if the program executes the 
call repeatedly on each specific unit of the public structure (for 
example, DKO:, DKl:, and upward) rather than on the entire public 
structure (SY:). 
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7.2.17 Monitor Tables And FCB Or DDB Information 


The two monitor table SYS system function calls to FIP return to the 
user program either an address or a data value. They are commonly 
employed with the PEEK function to read various system parameters and 
tables which give configuration and run time information. Because it 
is beyond the scope of this manual to describe the monitor, this 
section only briefly describes the information returned by the monitor 
table functions. Section 7.3 describes the use of the PEEK function 
for certain convenient programming operations. 


In this section, each item of information described is denoted by a 
name in all upper case letters. This name is the same one used to 
identify the information in the RSTS/E assembly listings. If the name 
is enclosed by parentheses, the information returned is an address of 
the data described. If the name is not enclosed by parentheses, the 
information returned is the actual data value. For example, the get 
monitor table (part I) call returns NULINE in byte 3. The value 
returned is the number of terminal lines configured on the system. 
However, in bytes 11 and 12 is (JOBTBL), the address of the table of 
jobs. The user program can inspect the address by using the PEEK 
function. 
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7.2.17.1 Get Monitor Tables - Part I ~ Not Privileged (F0=-3) 


Data Passed: 


Byte(s) Meaning 
1 CHRS$ (6%), the SYS call to FIP 
2 CHR$(-3%), the get monitor tables (part I) code 
3-30 Not used. 
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Data Returned: 


Byte (s) 
1-2 


3 


21-22 


23-24 


25-26 


27-28 
29-30 


Possible Errors: 


Meaning 
Not used 


NULINE - the number of keyboards configured on the 
system 


MAXCNT ~ the maximum job number allowed during the 
current time sharing session 


(DEVCNT) - the table of maximum unit numbers for 
all devices configured on the system 


(DEVPTR) - the table of pointers to device DDBs 
(CORTBL) - the memory allocation table 

(JOBTBL) - the job table 

(JBSTAT) - the job status table 

(JBWAIT) - the table of job wait flags 


(UNTCLU) - the table of unit cluster sizes for 
mounted disks 


(UNTCNT) - the status table of the error counts 
and all devices on the system and the count of 
open files on each device 


(SATCTL) - the table of free block counts for each 
disk (other than swapping disks) on the system. 
The table SATCTL contains the least significant 
word (16 bits) of the double precision unsigned 
integer (32 bits) count of free blocks. Each word 
applies to a separate disk unit. 


(TBLNAM) - the program name table 


(SATCTM) - the table of free block counts for each 
disk (other than swapping disks) on the system. 
The table SATCTM contains the most significant 
word (16 bits) of the double precision unsigned 
integer (32 bit) count of free blocks. Each word 
applies to a separate disk unit. 


Current date in internal format 


Not used. 


No errors are possible. 
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7.2.17.2 Get Monitor Tables - Part II - Not Privileged (F0=-12) 


Data Passed: 


Byte(s) 


Data Returned: 
Byte(s) 
1-2 


3-4 


5-6 


7-8 


21-22 


23-24 


25-26 


27-30 


Possible Errors: 


Meaning 
CHRS (6%), the SYS call to FIP 


CHR$(-12%), the get monitor tables (part II) code 


Not used. 
Meaning 
Not used 
(FREES) - the table of free (small and large) 


buffer information 


(DEVNAM) - the device name table 

(TTILST) - the keyboard input CSR table 

(TTSLST) - the modem default list 

(TTYHCT) - the number of hung terminal errors 
since system start up 

(JOBCNT) - current number of jobs, current job 
number limit, configured job number limit 

Reserved 

(ERRCTL) - error logging control data 

(TRLMES) - the table of eligible message receiving 
jobs 

(LOGNAM) ~ the table of logical names for mounted 
disks 

(JOBRES) ~ the table of job residency pointers 


(CORMAX) ~ the word containing the size of memory 
physically present on the system. This value is 
updated after the RESET command in the TABLE 
OPTION is executed. 


Not used. 


No errors are possible. 
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7.2.17.3 Get Open Channel Statistics - Not Privileged (F0=-8) 


Data Passed: 


Byte (s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS(-8%), the get open channel statistics code 
3 CHRS(N%) where N% is the channel number (between 0 


and 15) of either the FCB or DDB 


4-30 Not used. 


Data Returned: 


Byte(s) Meaning 
1-2 Not used 
3-4 Word 1 of either the FCB or DDB 
5-6 Word 2 of either the FCB or DDB 
27-28 Word 13 of either the FCB or DDB 
29-30 Word 14 of either the FCB or DDB 


Possible Errors: 
Meaning ERR Value 
I/O CHANNEL NOT OPEN 9 


The channel specified in byte 3 of 
the call is not open. 


Discussion: 


The layout of an FCB and DDB for each device configured on the system 
is in the listing of the TBL.LST file created during system 
generation. 


The use of this call is rendered obsolete by the STATUS variable 
described in Section 12.3.5 of the BASIC-PLUS Language Manual. 
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7.2.18 Enabling and Disabling Disk Cacheing - Privileged (F0=19) 


Data Passed: 


Byte(s) Meaning 
1 CHR$ (6%), the SYS call to FIP 
2 CHRS$ (19%), the enable and disable disk cache code 
3 CHRS$(N%) where N% is 0 to enable the disk cache 


and non-zero to disable the disk cache 
4-30 Not used. 
Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 
ILLEGAL SYS() USAGE 18 


An attempt by a non-privileged job to execute this call. 


Discussion: 


This function enables or disables the disk cache. 
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7.2.19 Run-Time System Control 
A privileged user can conduct time-sharing operations with an 
auxiliary run-time system supplied by DIGITAL. This section describes 


SYS System Function Calls -17 and -18, used to build auxiliary 
run-time systems. 


7.2.19.1 Name A Run-Time System - Privileged (F0=-17) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS$ (-17%), the name run-time system code 
3 CHRS(N%) where N% is the channel number 
4-7 Run-time system name in RAD5O 
8-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning ERR Value 


I/O CHANNEL NOT OPEN 9 
The channel specified in byte 3 of the call is not open. 


ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged job to execute this call. 


Discussion: 


This SYS function provides the association required for a specially 
tailored module on the system disk to be accessed as a run-time 
system. This association is normally made during the system library 
build procedure and is not required again unless the system is 
regenerated. 
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7.2.19.2 Add A Run-Time System ~ Privileged (F0=-18) 


Data passed: 


Byte (s) 


27-30 


Data Returned: 


Possible Errors: 


Meaning 
CHRS (6%), the SYS call to FIP 
CHR$ (-18%), the run-time system manipulation code 
Not used. 
Run-time system name in RAD50 
Not used. ° 
Maximum allowed user image size, in K 
Maximum allowed user image size, in K 
Allowed user image size, in K, at initialization 
Reserved; must be 0 
Not used. 
Device name 
Unit number 
Unit number flag 


Not used 


No meaningful data is returned. 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
An attempt by a non~privileged job 
to execute this call; illegal parameters. 


NO ROOM AVAILABLE FOR FCB 32 
A small buffer is not available for FCB. 


NO RUN-TIME SYSTEM 41 
Auxiliary run-time system cannot be found 


Discussion: 
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This call adds the appropriate name to the run-time system table in 
memory. This action is necessary since the initialization code 
establishes a new table each time system start-up occurs. This call 
ensures that the appropriate name and parameters are entered in the 
table. 


The maximum and minimum user image sizes of the BASIC run-time system 
are set to 16K and 2K, respectively. These values are in reference to 
the user's job swappable image, not the size of the run-time system 
itself. 


Bytes 17 and 18 specify the requested size of the run-time system at 
initiatlization. If possible, this space is reserved when the 
run-time system is initialized. 
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7.2.19.3 Remove A Run-Time System - Privileged (F0=-18) 


Data Passed: 
Byte(s) 


1 


Data Returned: 


Possible Errors: 


Meaning 
CHRS (6%), the SYS call to FIP 
CHRS (-18%), the run-time system manipulation code 
CHRS$ (4%), remove run-time system 
Not used. 
Run-time system name in RAD50 


Not used. 


No meaningful data is returned. 


Meaning ERR Value 


ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged job 
to execute this call; illegal parameters. 


NO RUN-TIME SYSTEM 41 
Auxiliary run-time system cannot be found. 


ACCOUNT OR DEVICE IN USE 3 
Removal of the run-time system is not 
allowed while it is being used. 


Ve etk es aN 


fo 
cD 


Removal of the default run-time system is 
not allowed. 


Discussion: 


The SHUTUP system program automatically performs the remove action 


when time-sharing 


Operatons are terminated. The module entry is 


deleted from the run-time system table. 
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7.2.19.4 Load A Run-Time System - Privileged (F0=-18) 


Data Passed: 


Byte(s) Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHRS$ (-18%), the run-time system manipulation code 
3 CHRS$ (2%), load run-time system 
4-6 Not used. 
7-10 Run-time system name in RAD50 
11-12 Loading address 
13 128=Permanent residency; 0=Temporary residency 
14 1=Read/Write system; 0=Read only system. 
15-20 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 


Meaning 


ILLEGAL SYS() USAGE 
An attempt by a non-privileged job 
to execute this call; illegal parameters. 


NO ROOM FOR USER ON DEVICE 
Run-time system is too large for available 
storage space. 


ACCOUNT OR DEVICE IN USE 
More than one job is attempting to load 
a run-time system at the same time. 


NO RUN-TIME SYSTEM 
Auxiliary run-time system cannot be found. 
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ERR Value 
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Discussion: 


This call loads the run-time system into memory at the 1K _ section 
specified. The run-time system is loaded from low memory to high 
memory at its defined initialized size, if possible. To be loaded 
without error, enough contiguous user Space must be available starting 
at that location. The location specified in bytes ll and 12 is the 
location at which the run-time system is loaded during the current 
time-sharing session. A -~l value in these bytes specifies the 
previous load address of this run-time system, if any. 


The section of memory chosen must not fragment the user job space to 
prevent the run-time system from executing a job. For example, assume 
a system has 24K words of user space available between the 36K and 60K 
sections of memory. Assume also that a job requires 18K words of user 
Space to run and that the run-time system requires 4K words when 
resident. If the loading address is 36K, the space between 40K and 
60K remains available for an 18K job to run. If the loading address 
is 42K, however, the user space is fragmented from 36K to 42K and from 
46K to 60K. An 18K job area is not available to execute a job using 
this auxiliary run-time system. 
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7.2.19.5 Unload A Run-Time System - Privileged (F0=-18) 


Data passed: 


Byte(s) , Meaning 
1 CHRS (6%), the SYS call to FIP 
2 CHR$(-18%), the run-time system manipulation code 
3 CHRS (6%), unload run-time system 
4-6 Not used. 
7-10 Run-time system name in RAD50 
11-30 Not used. 


Data Returned: No meaningful data is returned. 


Possible Errors: 
Meaning ERR Value 
ILLEGAL SYS() USAGE 18 
An attempt by a non-privileged job 
to execute this call; illegal parameters. 


NO RUN-TIME SYSTEM 41 
Auxiliary run-time system cannot be found. 


Discussion: 


This call frees the portion of memory occupied by the run-time system. 
The memory is made available as user job space. 
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7.3 THE PEEK FUNCTION 


The PEEK function allows a privileged user to examine any word 
location in the monitor part of memory. The user program can examine 
words in smail or large buffers, in the resident portion of the file 
processor, and in the low core and tables section of memory. The 
function does not allow a user program to examine the contents of 
another user's program. 


A privileged program executes the PEEK function in the following 
manner. 


It = PEEK (J$%) 


The function takes an (even) integer argument (J%) and returns an 
integer value (I%). The value returned is the contents of the address 
in memory specified by the argument. Since, on the PDP-1l computer, 
addresses of word locations are always even, and odd addresses 
indicate byte locations, the user must always be careful to specify an 
even integer address as the argument to PEEK. To examine an odd 
address, the program must specify the next lower integer as the 
argument to PEEK. The contents of the odd address is the high order 
byte of the value returned by PEEK. 


The PEEK function is normally used to examine either addresses 
returned by get monitor tables calls or addresses of fixed monitor 
locations. 


The following are possible errors generated by incorrect usage of the 
PEEK function. . 


Meaning ERR Value 


PROTECTION VIOLATION 10 
An attempt by a non-privileged user 
to execute this call 


UNIBUS TIMEOUT FATAL TRAP 33 
The address specified as an argument 
to PEEK is either odd or out 
of range of the allowed addresses. 


MEMORY MANAGEMENT VIOLATION 35 
The address specified as an argument 
to PEEK is illegal (not mapped 
in the monitor). 
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7.3.1 Fixed Locations In Monitor 
The following information is stored in fixed locations in the monitor 


part of memory and is obtained by executing a PEEK(X%) where X% is the 
address shown. 


Address 
(decimal) Name Meaning 
36 (word) IDATE The date when the system was last 
started by START 
38 (word) ITIME The time of day when the system was last 
started by START 
512 (word) DATE Current system date 
514 (word) TIME Current time of day 
518 (byte) JOB Job number times 2 of the job currently 
running (always is the user's own job 
number ) 
520 (word) JOBDA Address of the job data block (JDB) of 


the currently running job (always the 
user's own job data block) 


7.3.2 Useful Routines 


7.3.2.1 Finding The Current Project-Programmer Number - Two methods 
exist for a program to determine the project-programmer number under 
which it is running. The first method, the only one available to 
non-privileged users, is to execute the read or read and reset 
accounting data FIP function (F0=14). If the index and the 
project-programmer number passed in the call are both 0, the 
project-programmer number returned in bytes 5 and 6 is that of the 
program executing the call. This first method is slow because it 
requires FIP handling and possibly requires one or more disk accesses. 


The second method, available only to privileged users, is faster and 
involves executing the PEEK function to examine two bytes in the job 
data block (JDB) of the job. The contents of the JDB bytes 26 and 27 
is the project-programmer number of the current job. The high byte 
returned by PEEK is the project number; the low byte is’ the 
programmer number. The address of the JDB of the currently running 
job is in the fixed monitor location JOBDA (address 520). The 
following statement 


A% = PEEK(PEEK(520%) + 26%) 
puts the project-programmer word into the variable A%. The following 
statements put the project number in B% and the programmer number in 
Cs. 


BS 
CB 


SWAP$ (A%) AND 255% 
A% AND 255% 
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7.3.2.2 Determining An ATTACHED Or DETACHED Condition - Only one 
method exists for a program to determine whether or not it is attached 
to a terminal. It is beyond the scope of this manual to describe the 
mechanics of the method. It is sufficient to say that the method 
determines whether or not a console keyboard exists for the job. The 
following statements show the procedure. 


10 IF ( (PEEK (PEEK (PEEK (PEEK (5208) ) ) +23) AND 255%) =(PEEK(518%) AND 255%) 
AND 
(PEEK (PEEK (PEEK (PEEK (5208) ) ) +308) AND 8192%) =8192%) 
THEN GOTO 20 
ELSE GOTO 30 
20 REM: THIS LINE IS REACHED ONLY IF THE JOB IS ATTACHED TO A TERMINAL 
25 PRINT "ATTACHED" 
: STOP 
30 REM: THIS LINE IS REACHED ONLY IF THE JOB IS DETACHED 
35 STOP 


Line 10 determines the attached or detached condition. The 
parentheses are important. 


Once a program determines that it is attached to a terminal, it 
normally is not necessary to find the keyboard number. The program 
has normal access to the terminal by executing either an OPEN "KB:" 
statement on a free channel or a PRINT or INPUT statement without a 
channel specified. 
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CHAPTER 8 


PROGRAMMING CONVENTIONS AND HINTS 


Many RSTS/E system programs are designed to run by methods other’ than 
by the RUN command. The following are some of the alternative 
methods. 


a. At a logged out terminal by means of LOGIN. For example, SYS 
typed at a logged out terminal causes the SYSTAT system 
program to run. 


b. At a terminal by means of a CCL command. For example, the 
standard CCL command QUE runs the QUE system program. 


It is useful for the system manager to be able to duplicate some of 
these actions in his own utility programs on his system. Also, the 
system manager can alter system programs to tailor them to local 
installation needs. The guidelines in the following sections describe 
how to perform these actions. 


PROGRAMMING CONVENTIONS AND HINTS 
8.1 RUNNING A PROGRAM FROM A LOGGED OUT TERMINAL 


A program runs from a logged out terminal by means of the LOGIN system 
program. When the user types characters at a terminal not logged in, 
the monitor runs LOGIN which compares the characters typed with those 
it is designed to recognize. LOGIN is designed to accept a command 
line from a logged out terminal and chain to a system program. 


The following discussion employs the SYSTAT system program aS = an 
example of coding both LOGIN and a user program to run at a logged out 
terminal. The monitor runs LOGIN at line 32000 if a line is typed at 
a terminal not logged into the system. LOGIN extracts the characters 
typed and compares the leftmost characters typed with commands in a 
set of DATA statements between lines 32200 and 32299. If a command 
matches the characters and the third item in the DATA statement is 4, 
LOGIN puts the command line extracted in the core common area and 
chains to line 32000 of the program and account specified in the 
second element of the DATA statement. Thus, for SYS typed at a logged 
out terminal, LOGIN chains to the SYSTAT program in the system library 
account. The following statement in LOGIN ensures that action. 


32280 DATA SYS, $SYSTAT, 4 


To chain to a certain program, the user can supply a DATA statement in 
the same format between lines 32101 and 32199 in LOGIN. For example, 
to run a program named HELP under account [2,2] in response to a 
command named WHAT, insert into LOGIN.BAS a DATA statement similar to 
the following. The DATA statement must include an account number 
since there is no default account when running at a terminal not 
logged into the system. 


32190 DATA WHAT, "[2,2]HELP", 4 


After LOGIN is compiled and stored in the system library account, the 
program HELP under account [2,2] starts running at line 32000 whenever 
WHAT is typed at a logged out terminal. 


The program chained to at line 32000 must contain statements which 
process the information passed to it in core common as a command line. 
Provision must also be made for resetting variables used as flags and 
for initiating error handling. Because a job not logged into the 
system has no project-programmer number, the program chained to cannot 
assume a default project-programmer number when opening a file. The 
CHAIN command in the LOGIN system program does not drop the _ special 
login privileges which are afforded by not being logged in. The 
program to which LOGIN chains can therefore read or write any file on 
the system because it retains the full privileges. To implement 
protection, the program itself must perform the protection check. 
When a logged out job terminates, it can print the BYE message to 
inform the user that the terminal is still logged out. When the 
logged out job executes an END statement or a STOP statement, the 
system immediately removes the program from memory and leaves the user 
terminal in a logged out state. 
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8.2 DESIGNING A PROGRAM TO RUN BY A CCL COMMAND 


By means of the CCL command option at system generation time, the 
system manager can specify unique commands which, when typed on a 
logged in terminal, load and run BASIC-PLUS programs from the system 
library account. The monitor maintains a table of such commands and 
programs and, by convention, chains to a program at line 30000. 


To pass information to the program, the monitor writes to the core 
common area the entire line typed at the terminal (after all spaces 
have been deleted) including the command typed. The user program must 
extract the data from core common and parse the entire line typed. 
This action allows the user to design a program to run by several CCL 
commands. AS aoconvention, programs supplied by DIGITAL and invoked 
by standard CCL commands reserve lines 30000 to 30999 for routines 
which parse the command line, check for errors, and dispatch to 
routines within the program. 


8.3 CHANGING LOGIN TO SET A DIFFERENT SWAP MAXIMUM 


The LOGIN system program sets the swap maximum to 8K words for all 
users except those whose project numbers are one. This action means 
that privileged users run with a swap maximum of 16K words. Since, on 
many systems, programs must run under non-privileged accounts in job 
areas larger than 8K words, it is necessary to modify LOGIN to set a 
Swap maximum larger than 8K words. 


To modify the LOGIN.BAS program, the user must alter the J% = 8% 
statement in the first physical line of the multiple statement line at 
line number 15010 and compile the program on the system library 
account. The following statement sets the priority, run burst, and 
Swap maximum factors. 


15010 J% = 8% 
: J% = 16% IF (A% AND -256%) - 2563 
: IS = SYS (CHRS$ (6%) +CHRS (-13%) +CHRS (-1%) + 
CHRS (-1%)+CHRS (-2%) + 
CHRS( 0%)+CHRS( 6%)+ 
CHRS (-1%)+CHRS( J%)) 
: RETURN 


Change the value 8% in the statement J% = 8% to any value less than or 
equal to the current default swap maximum used at system start-up 
time. Re-~compile and re-protect the program on the system library 
account with protection code <60> as follows. 


COMPILE SY0:LOGINS 

READY 

NAME "LOGIN.BACS" AS "LOGIN.BACS<232>" 
READY 


It is recommended that the system manager not replace the original 
source file LOGIN.BAS with the modified version. 
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8.4 PROGRAMMING HINTS 


These sections describe suggested programming methods in two 


categories: reducing overhead storage space in programs and 
decreasing required access time for certain operations. Normally, 
these are mutually exclusive goals. Space is most often saved at the 
expense of time, and vice versa. In the sections that follow, a 


discussion of either commodity ignores the other, so it is up to the 
user to decide when each of these methods can best be used for a 
particular application. Of course, when both space and time are 
optimized, as is the case with some of these methods, the entire 
RSTS/E system as well as the individual program benefits. 


8.4.1 Storage Space Overhead 


Certain steps can be taken to reduce overhead significantly. This 
section describes some of the most efficient methods to optimize the 
storage space available on a RSTS/E system. 


Combining statements on a line with the use of colons or backslashes 
saves statement header space. When using multiple statement lines, 
remember the maximum line length is 256 characters. 


Verbs that always require a statement header, regardless of where they 
occur, are: DATA, DEF, DIM, FNEND, FOR and NEXT. Whenever possible 
these statements should be first on a line to reduce statement header 
overhead. 


Statements such as INPUT, which may generate errors, should always be 
first on a line because a RESUME statement, when executed from an 
error handling routine, resumes program execution at the nearest 
preceding statement header. Similarly, since a GOTO statement begins 
execution only at the first statement of the specified line, the 
beginning of each routine in a program should be the first statement 
on a line. 


Use the exclamation point (!) within statement lines to indicate 
remarks. The REM statement or an exclamation point with its own line 
number requires a 12-byte statement header. 


In addition ot the storage space used when referencing a constant or 
variable, separate space is required to store the value. This space 
is required for constants every time they are referenced. Once a 
variable is defined, however, further references generate no more 
space. For this reason, frequently used constants should be declared 
as variables. For example: 


10 A& = 278%: BS = 278% 
requires more storage space than: 


10 A&® = 278%: B& = A& 
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And the following statement, accomplishing the same thing, uses. the 
least storage space: 


10 A&%,B% = 278% 


In some cases assigning a temporary variable saves vector addressing 
Space. For example, consider this program segment: 


10 FOR I% = 1% TO N&: 


S 


S + X(1%): S2 = $2 + X(I%) * X(I8) 
20 NEXT 1% 


Assigning a new variable (T), equal to an indexed variable (X(I$)) 


decreases the number of bytes of storage area as follows: 


10 FOR I% = 1% TO NB: 


T 


X(I%): 
S=S+T: S82 =S2+T7 *T 
20 NEXT I$ 
In addition, the example shown above executes guickly since 
recalculation of vector addresses is eliminated. Similarly, 
previously calculated items should be re-used. For example: 
10 D = SOR(B°2 - 4*A*C) /23*A;: 
PRINT -B/2%*A + SQR(B°2 - 4*A*C)/23*A; 
~B/2%*A - SQR(B°2 - 4*A*C)/2$*A 
obviously should be written: 
10 D = SQR(B°2 - 4*A*C)/2$*A; 
PRINT -B/2$*A + D; -B/23*A - D 


On the other hand, certain intermediate terms should be deleted. For 
example: 


20 A=B+C: D A+t+E: F=D+G 


should be condensed to: 
20 F=Bt+tCtHE+#G 


unless the variables A and D are to be used independently later in the 
program. 


Use integer variables when possible, and always denote them with the 
percent sign (%). The subscripts in arrays should always be integers, 
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specified with % signs. Use integers in FOR/NEXT loops unless’ the 
STEP function value is not an integer. Every constant should include 
a % or a period (.) each time it is used. 


Variables with the same first character should be used when possible. 
For example: 


A, A&, AS, A(.ee), AS(--+) 5 AS(...) 
each have the same first character, but A and B do not, and because of 
the way BASIC-PLUS stores variables, they use more space. So if the 
variable R is used in the program, using R® is preferable to using 
another integer variable. 


Always use as few variables as possible; re-use these variables for 
even more space savings, since no additional overhead is needed. 


Variables do not have to be compared to zero explicitly. For example: 
30 IF M%< >0% THEN 80 

should be written: 
30 IF M% THEN 80 


Space can be saved by using subroutines instead of user-defined 
functions, but be sure to exit with RETURN (not GOTO) statements. 


Individual variable names are often more economical than arrays, since 
they require less overhead. But if arrays are used, always dimension 
them first and limit the use of MAT statements. 


Use implied FOR loops, which require less core and execute faster, 
than FOR/NEXT loops. For example: 


10 FOR I% = 1% TO 10%: 
R& = R828 
20 NEXT 1% 
can be written: 
10 R& = R$°2% FOR i% = 1% to 10% 


Including the implied FOR loop, above, uses approximately 30% less 
core and executes faster than the original statements. 


Similarly, WHILE and UNITL should be used when possible to replace 
loops. The statement, 


10 X% 


XB * XBs IF X%<L% THEN GOTO 10 
can be written: 


10 X% 


X% * X% WHILE X%<L% 
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When using multiple IF statements, always use the compound IF 
For example: 


100 IF X% = W% THEN 250 
110 IF X% = A% THEN 300 
120 IF X% = K% THEN 500 
130 IF X% = L% THEN 600 


can be rewritten as follows: 


100 IF X% = We THEN 250 ELSE 


IF X% = A% THEN 300 ELSE 
IF X% = K% THEN 500 ELSE 
IF X% = L% THEN 600 


format. 


This compound IF format, above, saves 35% more core than the single IF 


format. 


When a variable is to be compared to some continuous range of 


values, 


replace the IF statements with an ON-GOTO statement. For example: 


100 IF X% = 4% THEN 250 ELSE 
IF X% = 5% THEN 300 ELSE 
IF X% = 6% THEN 500 ELSE 
IF X% = 7% THEN 600 


should be replaced with: 


100 ON X%-3% GOTO 250,300,500,600 


A similar technique can be used with strings. The following example: 


80 IF A$ = "A" THEN GOTO 100 ELSE 
IF A$ = "B" THEN GOTO 200 ELSE 
IF AS = "C" THEN GOTO 300 ELSE 
IF AS = "D" THEN GOTO 400 


can be rewritten: 
80 X% = ASCII (AS$)-64%: ON X% GOTO 100,200,300, 400 


Random string responses can be tested also. For example, to 
AS with the letters X,K,B and Y, use the following statement: 


80 ON INSTR(1%,"XKBY",AS) GOTO 100,200,300, 400 


compare 
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8.4.2 Decreasing Access Time 


There are a number of ways access time can be saved once data or 
programs are stored on disks. The BASIC-PLUS Language Manual 
describes some of these methods (for example, see Section 11.5 in that 
manual). 


Methods of setting up files are equally important and are discussed in 
this section. Most of these methods can be employed by users, but 
some of them may require the assistance of the system manager. 


Open files at the beginning of a program and pre-extend them to their 
maximum size. Also, pre-allocate scratch data files and, when through 
using them, simply close them instead of killing them. In this way, 
they can be re-used without wasting disk space and, ultimately, access 
time. These technigues tend to reduce directory fragmentation, 
decreasing access time. 


Keep large, frequently used files on separate disks. When two files 
are often opened at the same time, they too should reside on separate 
disks. Also, production files and accounts should be kept separate 
from development and scratch files when possible. If they cannot be 
kept on separate disks, they should at least be maintained in separate 
accounts. 


File and pack clustersizes should be optimized, as mentioned in the 


BASIC-PLUS Language Manual and the RSTS/E System Manager's Guide, 
respectively. 
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8.4.3 String Manipulation 


end all strings to their maximum length at the beginning of a 
as follows: 


3 oct 


10 X$ = SPACES (L$) 


where L% is the maximum length of the string. Then use LSET and RSET 
statements (don't re-use LET) to move data into the string. 


The difference between LET and LSET can be seen with the diagrams 
shown below. Consider the following statements: 


10 LET A$ "ABCD" 


20 LET C$ = "EFG" 


AS ———» "ABCD" 
cs are a "RPG" 
When the next statement is executed: 


30 LET C$ = AS 


AS a "ABCD" 
C$ 


C$ points to the same part of the I/O buffer as does AS. The old 
string, "EFG", iS wasted space. Note the effect of the LSET 
statement: 


40 LSET C$ = A$ 


AS —————» "ABCD" 


a WA 


ne Rr 
Co —— “SABC 


When a null string is concatenated to A$, the string C$ contains the 
contents of A$, but no longer points to the I/O buffer: 


50 LET cs = AS + wie 


AS ———————» "ABCD" 


CS —————» "ABCD" 


8-9 
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LSET and RSET statements move data; LET statements move pointers. 
Proper use of LSET and RSET prevents generation of wasted space, and 
execute faster than LET statements. 

The following three algorithms truncate trailing blanks from a data 
record (for example, a card image). The first two user-defined 
functions input a string and return the same string without trailing 
blanks and CR/LF. 


The slowest algorithm successively reassigns the argument until it 
ends with a non-blank: 


1000 DEF FNT$(XS): 
S$ = LEFT(X$,LEN(X)-13) 
WHILE RIGHT (X$,LEN(X$)) <= " " 
AND LEN (X$)>0% 
1010 FNT$ = S$ 
1020 FNEND 


The following algorithm is much more efficient. It scans backwards 
until a non~blank character is found. Only one assignment is made. 


200 DEF FNWS (XS): 
GOTO 2010 IF MID(X$,X%,1%)>" " 
FOR X% = LEN(XS) TO 0% STEP -1% 
2010 FNWS = LEFT(XS$,X%) 
2020 FNEND 
The most efficient algorithm uses the data buffer directly, avoiding 
the assignment caused by the user-defined function. L% is the record 
length. 
3000 FOR K% = L% TO 1% STEP -18%: 
FIELD #2%, K%-1% AS L$, 1% AS LS: 
IF L$>" " THEN 
FIELD #2%, K% AS L$: GOTO 3020 
3010 NEXT K%: LSET L$ = "" 
3020 ! DONE 


The more efficient algorithms are more cpu-bound because they do less 
swapping. 
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MAGTAPE LABEL FORMATS 


A magtape is said to be in DOS format when the tape labels associated 
with its files are in DOS format. Similarly, a magtape in ANSI format 
is one whose labels are in ANSI format. The following sections 
discuss the differences between DOS and ANSI formats, and how the 
system handles magtapes written in either format. 


A.1 DOS MAGTAPE FORMAT 


This section describes the labels and data blocks on a magtape in DOS 
format, as well as the order in which these items are placed on the 
tape. For purposes of explanation, assume that the particular Mag tape 
under discussion has three files, each containing ten data blocks. 


The first part of the magtape is a physical beginning of tape (BOT), a 
reflective (silver) marker. Immediately past this marker is the first 
tape label followed, in this case, by ten data blocks and an end of 
file (EOF) record. 


All magtape files begin with a tape label, contain any number of data 
blocks (default size is 512 bytes per block), and terminate with an 
end of file record. DOS files may even contain zero data blocks, but 
a label and end of file record are always required for each file. 


data blocks ——e 


Figure A-1l 
A DOS Magtape File 
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Following the first file, another label begins the second file. This 
label is also followed by ten data blocks and an end of file record. 
This second file is immediately followed by the third and last file, 
which consists of a tape label, ten data blocks, and an end of file 
record. In addition, since the third file on this tape is also the 
last one, two more end of file records follow. The magtape has three 
end of file records at this point, signifying a logical end of tape 
(LEOT). 


Logical End of Tape (LEOT) 
jwa——— lst file ———w»|<«—— 2nd file ———»|~<—-3rd file —+| { 


PHYSICAL 


INACCES: FORMATION 
iC SIBLE INFO EOT 


10 data blks 10 data blks 


10 data blks 


cme re 


Figure A-2 
DOS Magtape Consisting of 3 Files of 10 Data Blocks Apiece 


Once the logical end of tape is written on the magtape, it can be 
written over, but it cannot be read over. Therefore, all information 
beyond the logical end of tape is inaccessible. 


A magtape can contain no files. In that case, three end of file 
records simply follow the beginning of tape marker. 
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A.1.1 DOS Labels 


The record label which specifies the beginning of a magtape file in 
format is 14 bytes long. Table A-1l identifies the information 


Table A-1l 
DOS Record Label Bytes 


words in RADIX 50 

word in RADIX 50 

byte in binary 

byte in binary 

byte in binary (always 155(10)) 
byte of zero 

word in internal date format 
word of zero 


File name 
File extension 


Programmer number 
Project number 
Protection code 
Unused 

Creation date 
Unused 


BRP Pe PED 


The project-programmer number is the account number of the current 
user, unless some other number is specified in the OPEN statement. If 
Magtapes are to be interchanged with DOS-11 systems, a problem may 
occur since RSTS-ll treats project-programmer numbers as decimal 
values, and DOS-1ll treats this number (called a UIC under DOS-11) as 
an octal value. To avoid interchange problems, simply write all files 
on the tape with a [1,1] project-programmer number, which is the same 
in both decimal and octal. For example: 


100 OPEN "MTO:ABC[1,1]" FOR OUTPUT AS FILE 13% 


would accomplish this. Note that the project-programmer number is 
part of the filename string. There could be several files named "ABC" 
on a tape having different project-programmer numbers associated with 
them. Often a failure to find a file on a magtape is the result of 
forgetting to specify the correct account number. 


The protection code written by RSTS/E in the DOS label is always 155 
decimal (233 octal) which is acceptable to DOS-11. RSTS-11 and DOS-11 
use different protection code values. RSTS-ll ignores the value of 
the protection code when reading the file. This avoids interchange 
conflicts with DOS-1ll. 


MAGTAPE LABEL FORMATS 
A.2 ANSI MAGTAPE FORMAT 


This section describes the labels and data blocks on a magtape in ANSI 
format. Once again, for purposes of explanation, assume that the 
particular magtape under discussion has three files, each containing 
ten data blocks. 


The first part of the magtape is a physical beginning of tape 
reflective marker. The next item on the magtape is a volume label. 
(A volume is simply a reel of magnetic tape. A volume may contain 
part of a file, a complete file, or more than one file.) 


The first file actually begins with two labels, called header labels 
(HDRl1 and HDR2). These header labels are followed by an end of file 
(EOF) marker. In this case, ten data blocks are written immediately 
after the single EOF marker. The data blocks are followed, in order, 
by another EOF marker, two trailer labels (EOF1 and EOF2), and yet 
another EOF marker. 


All files in ANSI format begin with two header labels. An EOF marker 
is written on both sides of the data blocks. Two trailer labels 
follow, and the file is terminated by another EOF marker. When the 
file is created but no data blocks are written, all the above labels 
and end of file markers are still present. These labels and end of 
file markers are always required for each file. 


Figure A-3 
An ANSI Magtape File 


Following the first file, another set of two headers begins the second 
file. The second file is identical to the first one, consisting of 
the two header labels, one EOF marker written on each side of ten data 
blocks, two trailer labels and an EOF marker. 


The third file on the tape is identical to the first and second, and 
is followed by two more EOF markers, signifying a logical end of tape 
(LEOT). 
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Figure A-4 


ANSI Magtape Consisting of 3 Files of 10 Data Blocks Apiece 


Once the logical end of tape is written on the magtape, it can be 
written over, but it cannot be read over. Therefore, all information 
beyond the logical end of tape is inaccessible. 


A magtape must contain at least one complete set of header and trailer 
labels. In the case where no file exists on the tape (such as a newly 
zeroed magtape), a dummy file is present with a complete set of labels 
and end of file records. 


A.2.1 ANSI Labels 


All ANSI labels are 80 bytes long. Each label can be identified by 
its first three characters: VOL (volume), HDR (header), and EOF (end 
of file). The fourth character in each label further defines the 
sequence of the label within its group. For example, the first and 
second header labels are HDR1 and HDR2, respectively. 


A.2.1.1 Volume Label - 


the magtape is 


field name and contents 


Character 
Position 


(1)The JJJ and GGG in the Owner 
user's project and program numbers, respectively. 
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This label identifies which volume (reel) of 


being used. Table A-2 shows the character position, 


Table A-2 


Volume Label Format 


Field Name 
and RSTS/E Usage 


Label Identifier 
Label Number 


Volume Identifier 
(Volume label; one 

to six alphanumerics, 
blank padded) 


Accessibility 
(RSTS/E writes a 
space) 


Reserved 

Owner Identifier (1) 
D%B4431JJJIGGG 
Reserved 


Label Standard Version 


of each byte (character) 


Identification 


in the volume label. 


Contents 


1 to 6 alphanumeric 
characters. 


A space means no 
restrictions. 


Spaces 

The contents of this 
field are used for 
volume protection. 
Spaces 


1 


field represent the 
They are written as 


ASCII digits in decimal notation with leading zeros if needed. 


A.2.1.2 
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Header 1 Label (HDR1) - Table 


A-3 shows the character 


position, field name and contents of each byte in the header 1 label. 


Character 
Position 


Table A-3 


Header 1 Label Format 


Field Name 
and RSTS/E Usage 


Label Identifier 
Label Number 


File Identifier (2 to 
10 characters FILNAM. 
or FILNAM.EXT; blank 
filled) 


File-set Identifier 
(Volume Identifier from 
the VOL1 label) 


File Section Number 
(0001) 


File Sequence Number 


Generation Number 
(0001) 


Generation Version 
(00) 


Creation Date 
Today's date in 
specified format 


Expiration Date 
Today's date in 
specified format 


Accessibility 


Block Count 


System Code 
DECRSTS/E 


Reserved 


Contents 


1 
Any alphanumeric or special 


character in the ASCII code 
table 


Volume ID of first 
in the volume set 


Numeric characters; starts 
at 0001 
File number within volume 
set for this file; starts 
at 0001 


Numeric characters 


Numeric characters 


(SPACE) YYDDD or 
(SPACE)00000 if no date 


(SPACE) YYDDD or 
(SPACE)00000 if expired 
Space 

000000 

Name of system which 
produced the volume. Padded 


by spaces. 


Spaces 
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A.2.1.3 Header 2 Label (HDR2) - Table A-4 shows the character 
position, field name and contents of each byte in the header 2 label. 


Table A-4 
Header 2 Label Format 


Character Field Name 
Position and RSTS/E Usage Contents 


Label Identifier 
Label Number 
Record Format 


(U is the default) 
(S is unsupported) 


Fixed 
Variable 
Spanned 
Undefined 


Block Length Numeric Characters 
(512 is the default) Settable by FILESIZE option 


Record Length Numeric Characters 
Settable by CLUSTERSIZE option 


System Dependent Bytes 16-36 (Spaces) 
(M is the default) Byte 37 = A means first byte of 
record contains 
FORTRAN 
control character 


(Space) means LF/CR 
precedes each record 
M means record 
contains all form 
control information 


Buffer Offset (00) Numeric characters 00 on files 
means PDP~-1l produced tapes 


Reserved Spaces 
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A.2.1.4 End Of File 1 Label (EOF1) - The EOF1 label is identical to 
the HDR1 label except for characters 1-3 and 55-60. Table A-5 shows 
the character position, field name, and contents of each byte in the 
EOF1 label. 


Table A-5 
End of File (EOF) 1 Record Format 


Field Name 
and RSTS/E Usage 


Character 
Position 


Contents 


Label Identifier 


4 Label Number 1 
5-21 File Identifier (2 to Any alphanumeric or special 
10 characters) FILNAM. character in the ASCII code 
Or FILNAM.EXT; blank table 
filled) 
22-27 File-set Identifier Volume ID of first volume 
(Volume Identifier from in the volume set. 
the VOL1 label) 
28-31 File Section Number Numeric characters: starts 
(0001) at 0001 
32-35 File Seguence Number File number within volume 
set for this file; starts 
at 0001 
36-39 Generation Number Numeric characters 


(0001) 


Generation Version (00) Numeric characters 


Creation Date 
Today's date in 
specified format 


(SPACE) YYDDD 
(SPACE)00000 if no date 


Expiration Date 
Today's date in 
specified format 


(SPACE) YYDDD 
(SPACE)00000 if expired 


Accessibility Space 


Block Count File size in blocks 


System Code 
DECRSTS/E 


Name of system which 
produced the volume. Padded 
by spaces. 


Reserved 


Spaces. 
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A.2.1.5 End Of File 2 Label (EOF2) - The EOF2 label is identical to 
the HDR2 label except for characters 1-3. Table A-6 shows the 
character position, field name and contents of each byte in the EOF2 
label. 


Table A-6 
End of File (EOF) 2 Record Format 


Field Name 
and RSTS/E Usage 


Character 
Position 


Contents 


Label Identifier 


Label Number 


Record Format F = Fixed 

(U is the default) D = Variable 

(S is unsupported) S = Spanned 
U = Variable 


Numeric Characters 
Settable by FILESIZE option 


Block Length 
(512 is the default) 


Numeric Characters 
Settable by CLUSTERSIZE 
option 


Record Length 


Bytes 16-36 (Spaces) 
Byte 37 = A means first byte 
of 


System Dependent 
(M is the default) 


record 
contains FORTRAN 
control character 


(Space) means 


precedes each 
record 
= M means record 
contains all form 
control 
information 


Numeric characters 00 on 
files mean PDP-11 produced 
tapes 


Buffer Offset (00) 


Reserved Spaces 
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A.3 ZEROING MAGTAPES 


This section describes how a magtape is zeroed. See Section 4.18.7 of 
the RSTS-11 System User's Guide for the procedure for zeroing magtapes 


via the Peripheral Interchange Program (PIP). 

A magtape written in DOS format is zeroed in the following manner: 
1. Magtape is rewound. 
2. Three end of file (EOF) records are written on the tape. 
3. Magtape is again rewound. 

A magtape written in ANSI format is zeroed in the following manner: 
1. Magtape is rewound. 


2. A volume label (VOL1) is written on the tape. The volume 
identifier is in bytes 7 through 10, in RAD50. 


3. Two header labels (HDR1 and HDR2) are written on the tape. 

4. Two end of file (EOF) records are written on the tape. 

5. Two trailer labels (EOF1 and EOF2) are written on the tape. 

6. Three end of file (EOF) records are written on the tape. 

7. Magtape is again rewound. 
Notice that in the case of magtapes written in ANSI format, the two 
header labels (HDR1 and HDR2), two EOF records, two trailer labels 
(EOF1 and EOF2) and a final EOF record comprise a dummy file. Also, 
in both the DOS format and the ANSI format case, three EOF records are 


the last items written on the tape. These three EOF records form the 
logical end of tape (LEOT). 


APPENDIX B 


CARD CODES 


The RSTS card driver can be configured for one of three different 
punched card codes. These are DEC029 codes, DEC026 codes and 1401 
(EBCDIC) codes. The RSTS-11 DEC029 and DEC026 codes are the same as 
the DOS-11 card codes. The particular set of codes used on the system 
is determined by the system manager. In all cases, the end-of-file 
(EOF) card must contain a 12-11-0-1 punch or a 12-11-0-1-6-7-8-9 punch 
in column 0. 


CHARACTER — ASCII, , DECO29 DECA26 1461 | CHARACTER ASCIT,,  DEC@29 DECA26 1481 
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EOF is 12-11-@-1 punch or a 12-11-9-1-6-7-8-9 punch. 


APPENDIX C 


RADIX-50 CHARACTER SET 


Character ASCII Octal Equivalent 
space 40 
A-Z 101-132 
$ 44 
< 56 
unused 
0-9 60-71 


The maximum RADIX-50 value is, thus, 
47*50° + 47*50 + 47 = 174777 


The character/position table provides a convenient 
translating between the ASCII character set and 
equivalents. For example, given the ASCII string X2B, 
equivalent is (arithmetic is performed in octal): 


X = 113000 
2 = 002400 
B_ = 000002 
X2B = 115402 


Radix-50 
Equivalent 


means of 
Radix-50 
Radix-50 


Radix-5@ Character/Position Table 


Single Char. 
or Second Third 
First Char. Character Character 


993108 
666266 
611368 
614466 
617566 
622688 
625766 
631666 
634166 
637266 
642366 
£45466 
658566 
953666 
656768 
£62666 
665168 
676266 
973368 
676406 
1615628 
184662 
167766 
113666 
116182 
121266 
124368 
127468 : 3 
132598 unused unused 
135680 
148788 
1446628 
147168 
152266 
155368 
166462 
163568 
166688 
171768 
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APPENDIX D 


ASCII CHARACTER CODES 


ASCII ASCII ASCII 
Char- Decimal Char- RSTS Decimal Char- RSTS 
acter Value acter Usage Value acter Usage 


NUL FILL character 
SOH 

STX 

ETX CTRL/C 

EOT 

ENQ 

ACK 

BELL 


Backslash 


mm ZONK XM ES 


ODMAAIANAUABWNHEHE BQ 
oO 
K 
> 


or + 
Grave accent 


HORIZONTAL TAB 
LINE FEED 
VERTICAL TAB 
FORM FEED 
CARRIAGE RETURN 


“WOON KDAUBWNHEeE BAN: 


CTRL/O 


CTRL/Z 
ESCAPE! 


Vertical Line 
APOSTROPHE 


tas ANIM HK ECG tHORQAHDOBS RP wwe same adowa s| 


Tilde 
DEL RUBOUT 


< 
> 
2. 
@ 
A 
B 
c 
D 
E 
F 
G 
H 
I 
J 
K 
L 
M 
N 
O 
P 
Q 
R 
s 
T 
U 


APPENDIX E 


ERROR MESSAGES 


E.1 USER RECOVERABLE 


A (C) in the description of the error message indicates that program 
execution continues, following printing of the error message, if an ON 
ERROR GOTO statement is not present. Normally, execution terminates 
on an error condition, the error message is printed, and the system 
prints READY. The ERR column gives the value of the ERR variable (see 
Section 8.4, BASIC-PLUS Language Manual). 


ERR Message Printed Meaning 
1 BAD DIRECTORY FOR DEVICE The directory of the device 
referenced is in an _ unreadable 
format. 
2 ILLEGAL FILE NAME The filename specified is not 
acceptable. It contains 


unacceptable characters or the 

filename specification format has 

been violated. 

3 ACCOUNT OR DEVICE IN USE Removal or dismounting of the 
account or device cannot be done 
since one or more users are 
currently using it. 


4 NO ROOM FOR USER ON DEVICE Storage space allowed for the 
current user on the device 
specified has been used or the 
device as a whole is too full to 
accept further data. 


5 CAN'T FIND FILE OR ACCOUNT The file or account number 
specified was not found on _ the 


device specified. 


6 NOT A VALID DEVICE Attempt to use an illegal or 
nonexistent device specification. 


7 I/O CHANNEL ALREADY OPEN An attempt was made to open one of 
the twelve I/O channels which had 
already been opened by the program. 
(SPR) 
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11 
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13 
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ERROR MESSAGES 


DEVICE NOT AVAILABLE 


I/O CHANNEL NOT OPEN 


PROTECTION VIOLATION 


END OF FILE ON DEVICE 


FATAL SYSTEM I/O FAILURE 


USER DATA ERROR ON DEVICE 


DEVICE HUNG OR WRITE LOCKED 


KEYBOARD WAIT EXHAUSTED 


NAME OR ACCOUNT NOW EXISTS 


TOO MANY OPEN FILES ON UNIT 


ILLEGAL SYS() USAGE 


The device requested is currently 
reserved by another user. 


Attempt to perform I/O on one of 
the twelve channels which has not 
been previously opened in the 
program. 


The user was prohibited from 
performing the requested operation 
because the kind of operation was 
illegal (such as input from a line 
printer) or because the user did 
not have the privileges necessary 
(such as deleting a protected 
file). 


Attempt to perform input beyond the 
end of a data file; or a BASIC 
source file is called into memory 
and is found to contain no END 
statement. 


An I/O error has occurred on_ the 
system level. The user has_ no 
guarantee that the last operation 
has been performed. (SPR) 


One or more characters may have 
been transmitted incorrectly due to 
a parity error, bad punch 
combination on a card, or similar 
error. 


User should check hardware 
condition of device requested. 
Possible causes of this error 
include a line printer out of paper 
or high-speed reader being 
off-line. 


Time requested by Wait statement 
has been exhausted with no input 
received from the specified 
keyboard. 


An attempt was made to rename a 
file with the name of a file which 
already exists, or an attempt was 
made by the system manager’ to 
insert an account number which is 
already within the system. 


Only one open DECtape output file 
is permitted per DECtape drive. 
Only one open file per magtape 
drive is permitted. 


Illegal use of the SsyYS system 
function. 
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ERROR MESSAGES 


DISK BLOCK IS INTERLOCKED 


PACK ID'S DON'T MATCH 


DISK PACK IS NOT MOUNTED 


DISK PACK IS LOCKED OUT 


ILLEGAL CLUSTER SIZE 


DISK PACK IS PRIVATE 


DISK PACK NEEDS 'CLEANING' 


FATAL DISK PACK MOUNT ERROR 


I/O TO DETACHED KEYBOARD 


PROGRAMMABLE “C TRAP 


CORRUPTED FILE STRUCTURE 


DEVICE NOT FILE STRUCTURED 


ILLEGAL BYTE COUNT FOR I/O 


NO ROOM AVAILABLE FOR FCB 


The requested disk block segment is 
already in use (locked) by some 
other user. 


The identification code for the 
specified disk pack does not match 
the identification code already on 
the pack. 


No disk pack is mounted on _ the 
specified disk drive. 


The disk pack specified is mounted 
but temporarily disabled. 


The specified cluster size is 
unacceptable. 


The current user does not have 
access to the specified private 
disk pack. 


Non-fatal disk mounting error; use 
the CLEAN operation in UTILTY. 


Fatal disk mounting error. Disk 
cannot be successfully mounted. 


I/O was attempted to a hung up 
dataset or to the previous, but now 
detached, console keyboard for the 
job. 


ON ERROR-GOTO subroutine was 
entered through a program trapped 
CTRL/C. See a description of the 
SYS system function. 


Fatal error in CLEAN operation. 


An attempt is made to access a 
device, other than a disk, DECtape, 
or Imag tape device, as a 
file-structured device. This error 
occurs, for example, when the user 
attempts to gain a directory 
listing of a non-directory device. 


The buffer size specified in the 
RECORDSIZE option of the OPEN 
Statement or in the COUNT option of 
the PUT statement is not a multiple 
of the block size of the device 
being used for I/O, or is illegal 
for the device. 


When the user accesses a file under 
programmed control in RSTS-ll, a 
system control structure called an 
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ERROR MESSAGES 


UNIBUS TIMEOUT FATAL TRAP 


RESERVED INSTRUCTION TRAP 


MEMORY MANAGEMENT VIOLATION 


SP (R6) STACK OVERFLOW 


DISK ERROR DURING SWAP 


MEMORY PARITY FAILURE 


MAGTAPE SELECT ERROR 


MAGTAPE RECORD LENGTH 
ERROR 


NO RUN-TIME SYSTEM 


VIRTUAL BUFFER TOO LARGE 


VIRTUAL ARRAY NOT ON DISK 


MATRIX OR ARRAY TOO BIG 


VIRTUAL ARRAY NOT YET OPEN 


FCB reguires one small buffer and 
one small buffer is not available 
for the FCB. 


This hardware error occurs when an 
attempt is made to address 
nonexistent memory or an odd 
address using the PEEK function. 
An occurrence of this error message 
in any other case is cause for an 
SPR. 


An attempt is made to execute an 
illegal or reserved instruction or 
an FPP instruction when floating 
point hardware is not available. 


This hardware error occurs when an 
illegal Monitor address is 
specified using the PEEK function. 
Generation of the error message in 
situations other than using PEEK is 
cause for an SPR. 


An attempt to extend the hardware 
stack beyond its legal size is 
encountered. (SPR) 


A hardware error occurs when a 
user's job is swapped into or out 
of memory. The contents of the 
user's job area are lost but the 
job remains logged into the system 
and is reinitialized to run the 
NONAME program. 


A parity error was detected in the 
memory occupied by this job. 


When access to a magtape drive was 
attempted, the selected unit was 
found to be off line. 


When performing input from magtape, 
the record on magtape was found to 
be longer than the buffer 
designated to handle the record. 


Reserved. 


Virtual core buffers must be 512 
bytes long. 


A non-disk device is open on_ the 
channel upon which the virtual 
array is referenced. 


In-core array size is too large. 
An attempt was made to use a 


virtual array before opening the 
corresponding disk file. 
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ERROR MESSAGES 


ILLEGAL I/O CHANNEL 


LINE TOO LONG 


FLOATING POINT ERROR 


ARGUMENT TOO LARGE IN EXP 


DATA FORMAT ERROR 


INTEGER ERROR 


ILLEGAL NUMBER 


ILLEGAL ARGUMENT IN LOG 


IMAGINARY SQUARE ROOTS 


SUBSCRIPT OUT OF RANGE 


CAN'T INVERT MATRIX 


OUT OF DATA 


ON STATEMENT OUT OF RANGE 


Attempt was made to open a file on 
an I/O channel outside the range of 
the integer numbers 1 to 12. 
Attempt to input a line longer than 
255 characters (which includes any 
line terminator). Buffer 
overflows. 


Attempt to use a computed floating 
point number outside the range 
1E-38 <n< 1E38 excluding zero. 
If no transfer to an error handling 
routine is made, zero is returned 
as the floating point value. {C) 
Acceptable arguments are within the 
approximate range -89<arg<t+88. The 
value returned is zero. (C) 


A READ or INPUT statement detected 
data in an illegal format. For 
example, 1..2 is an improperly 
formed number, and 1.3 is an 
improperly formed integer, and xX" 
is an illegal string. (C) 


Attempt to use a computed integer 
outside the range -—32767<n<32767. 


If no transfer to an error handlin 
routine is made, zero is returne 


as the integer vaiue. (C) 


Integer or floating point overflow 
or underflow. 


Negative or zero argument to log 
function. Value returned is the 
argument as passed to the function. 


(C) 


Attempt to take square root of a 
number less than zero. The value 
returned is the square root of the 
absolute value of the argument. 
(C) 


Attempt to reference an array 
element beyond the number of 
elements created for the array when 
it was dimensioned. 


Attempt to invert a singular or 
nearly singular matrix. 


The DATA list was exhausted and a 
READ requested additional data. 


The index value in an ON-GOTO or 
ON-GOSUB statement is less than one 
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ERROR MESSAGES 


NOT ENOUGH DATA IN RECORD 


INTEGER OVERFLOW, 


DIVISION BY 0 


FOR LOOP 


Or greater than the number of line 
numbers in the list. 


An INPUT statement did not fina 
enough data in one line to satisfy 
all the specified variables. 


The integer index in a FOR loop 
attempted to go beyond 32766 or 
below -32766. 


Attempt by the user program to 
divide some quantity by zero. If 
no transfer is made to an _ error 
handler routine, a 0 is returned as 
the result. (C) 


ERROR MESSAGES 


E.2 NON-RECOVERABLE 


Message Printed Meaning 


ARGUMENTS DON'T MATCH Arguments in a function call do not 
match, in number or in type, the 
arguments defined for the function. 


BAD LINE NUMBER PAIR Line numbers specified in a LIST or 
DELETE comand were formatted 
incorrectly. 

BAD NUMBER IN PRINT-USING Format specified in the PRINT-USING 


string cannot be used to print one 
or more values. 


CAN'T COMPILE STATEMENT 


CAN'T CONTINUE Program was stopped or ended at a 
spot from which execution cannot be 
resumed. 


CATASTROPHIC ERROR The user program data structures 
are destroyed. This normally 
indicates a BASIC-PLUS This 
normally indicates a BASIC~PLUS 
malfunction and, if reproducible, 
should be reported to DEC ona 
Software Performance Report form 
(SPR). 


DATA TYPE ERROR Incorrect usage of floating-point, 
integer, or character string format 
variable or constant where some 
other data type was necessary. 


DEF WITHOUT FNEND A second DEF statement was 
encountered in the processing of a 
user function without an FNEND 
statement terminating the first 
user function definition. 


END OF STATEMENT NOT SEEN Statement contains too many 
elements to be processed correctly. 


EXECUTE ONLY FILE Attempt was made to add, delete or 
list a statement in a compiled 
(.BAC) format file. 


EXPESSION TOO COMPLICATED This error usually occurs when 
parentheses have been nested too 
deeply. The depth allowable is 
dependent on the individual 
expression. 


FIELD OVERFLOWS BUFFER Attempt to use FIELD to allocate 
more Space than exists in the 
specified buffer. 


ERROR MESSAGES 


FILE EXISTS-RENAME/REPLACE A file of the name specified in a 
SAVE command already exists. In 
order to save the current program 
under the name specified, use 
REPLACE, or RENAME’ followed by 
SAVE. 


FNEND WITHOUT DEF An FNEND statement was encountered 
in the user program without a 
previous function call having been 
executed. 


FNEND WITHOUT FUNCTION CALL A FNEND statement was encountered 
in the user program without a 
previous DEF statement being seen. 


FOR WITHOUT NEXT A FOR statement was encountered in 
the user program without a 
corresponding NEXT statement to 
terminate the loop. 


ILLEGAL CONDITIONAL CLAUSE Incorrectly formatted conditional 
expression. 
ILLEGAL DEF NESTING The range of one function 


definition crosses the range of 
another function definition. 


ILLEGAL DUMMY VARIABLE One of the variables in the dummy 
variable list of user-defined 
function is not a legal variable 
name. 


ILLEGAL EXPRESSION Double operators, missing 
operators, mismatched parentheses, 
or some similar error has’ been 
found in an expression. 


ILLEGAL FIELD VARIABLE The FIELD variable specified is 
unacceptable. 

ILLEGAL FN REDEFINITION Attempt was made to redefine a user 
function. 

ILLEGAL FUNCTION NAME Attempt was made _ to define a 


function with a function name not 
subscribing to the established 


format. 
ILLEGAL IF STATEMENT Incorrectly formatted IF statement. 
ILLEGAL IN IMMEDIATE MODE User issued a statement for 


execution in immediate mode which 
can only be performed as part of a 
program. 


ILLEGAL LINE NUMBER(S) Line number reference outside the 
range 1<n<32767. 


ERROR MESSAGES 


ILLEGAL MAGTAPE() USAGE Improper use of the MAGTAPE 
function. 


ILLEGAL MODE MIXING String and numeric operations 
cannot be mixed. 


ILLEGAL STATEMENT Attempt was made to execute a 
statement that did not compile 
without errors. 


ILLEGAL SYMBOL An unrecognizable character was 
encountered. For example, a line 
consisting of a # character. 


ILLEGAL VERB The BASIC verb portion of the 
statement cannot be recognized. 


INCONSISTENT FUNCTION USAGE A function is being redefined in a 
manner inconsistent in the number 
of type of arguments with one or 
more calls to that function 
existing in the program. 


INCONSISTENT SUBSCRIPT USE A subscripted variable is being 
used with a different number of 
dimensions from the number with 
which it was originally defined. 


K OF CORE USED Message printed by the LENGTH 
command, preceded by the 
appropriate number describing the 
user program currently in core to 
the nearest 1K. 


LITERAL STRING NEEDED A variable name was used where a 
numeric or character string was 
necessary. 

MATRIX DIMENSION ERROR Attempt was made to dimension a 
matriv tn mara than tw dimensions 


, 
or an error was made in the syntax 
of a DIM statement. 


MATRIX OR ARRAY WITHOUT DIM A matrix or array element was 
referenced beyond the range of an 
implicitly dimensioned matrix. 


MAXIMUM CORE EXCEEDED User program grew to be too large 
to run or compile in the area of 
core assigned to each user at _ the 
given installation. 


MISSING SPECIAL FEATURE User program employs a BASIC-PLUS 
feature not present on the given 
installation. 


MODIFIER ERROR Attempt to use one of the statement 
modifiers (FOR, WHILE, UNTIL, IF, 
or UNLESS) incorrectly. 


NEXT WITHOUT FOR A NEXT statement was encountered in 
the user program without a previous 
FOR statement having been seen. 


ERROR MESSAGES 


NO LOGINS Message printed if the system is 
full and cannot accept additional 
users or if further logins are 
disabled by the system manager. 


NOT A RANDOM ACCESS DEVICE Attempt to perform random access 
I/O to a non-random access device. 


NOT ENOUGH AVAILABLE CORE The already compiled user program 
is too large to run in the area of 
core assigned to each user at _ the 
given installation. 


NUMBER IS NEEDED A character string or variable name 
was used where a number was 
necessary. 

1 OR 2 DIMENSIONS ONLY Attempt was made to dimension a 


Matrix to more than two dimensions. 


ON STATEMENT NEEDS GOTO A statement beginning with ON does 
not contain a GOTO or GOSUB clause. 


PLEASE SAY HELLO User not logged into the system has 
typed something other than a legal, 
logged-out command to the system. 


PLEASE USE THE RUN COMMAND A transfer of control (as in a 
GOTO, GOSUB or IF-GOTO statement) 
cannot be performed from immediate 
mode, 


PRINT-USING BUFFER OVERFLOW Format specified contains a field 
too large to be manipulated by the 
PRINT-USING statement. 


PRINT~-USING FORMAT ERROR An error was made in the 
construction of the string used to 
supply the output format in a 
PRINT-USING statement. 


PROGRAM LOST-SORRY A fatal system error has occurred 
which caused the user program to be 
lost. 

REDIMENSIONED ARRAY Usage of an array or matrix within 


the user program has caused 
BASIC-PLUS to redimension the array 
implicitly. 


RESUME AND NO ERROR A RESUME statement was encountered 
where no error had occurred to 
cause a transfer into an error 
handling routine via the ON 
ERROR-GOTO statement. 


RETURN WITHOUT GOSUB RETURN statement encountered in the 
user program without a previous 


STATEMENT NOT FOUND 


STOP 


STRING IS NEEDED 


SYNTAX ERROR 


TEXT TRUNCATED 


TOO FEW ARGUMENTS 


TOO MANY ARGUMENTS 


UNDEFINED FUNCTION CALL 


WHAT? 


WRONG MATH PACKAGE 


ERROR MESSAGES 


GOS UB statement having been 
executed. 


program or source statement after 
changing the current scale factor. 
Use REPLACE and OLD or use RUN to 
execute without error. 


Reference is made within the 
program to a line number which is 
not within the program. 


STOP statement was executed. The 
user can usually continue program 
execution by typing CONT and_ the 
RETURN key. 


A number or variable name was used 
where a character string was 
necessary. 


BASIC-PLUS statement was 
incorrectly formatted. 


No BASIC-PLUS statement can be more 
than 255 characters long. 


The function has been called with a 
number of arguments not equal to 
the number defined for the 
function. 


A user-defined function may have up 
to five arguments. 


BASIC-PLUS interpreted some 
Statement component as a function 
call for which there is no defined 
function (system or user). 


Command or immediate mode statement 
entered to BASIC-PLUS could not be 
processed. Illegal verb or 
improper format error most likely. 


Program was compiled with an 
incompatible version of RSTS. 
Program source must be recompiled. 


Access time, 8-8 Characteristics function, 


Account information, 1-2 return file, 2-18 
Accounting dump, 7-93 Characters, 
Accounting information, 7-90 XON, 7-65 
Accounts, user, XOFF, 7-65 
creating, 7-60 CHR$ (27%) character, 7-68 
deleting, 7-62 Cleaning disk packs, 7-48 
Adding run-time systems, 7-111 CLOSE, 
Addresses, 7-117 file structured magtape, 2-9 
Advancing magtape, 2-14 non-file structured magtape, 2-10 
Allowable logins, setting, 7-89 Closing channels, 7-74 
ANSI label, 2-3, 2-7 CLUSTERSIZE option, 2-6 
ANSI labels, A-5 Cluster size, 1-5 
ANSI magtape files, A-4 directory, 1-6 
Appending data, 1-13 pack, 1-6 
ASCII mode, 6-1 Codes, card punched, B-1 
Assigning device, 7-30 Commands, CCL, 8-3 
ASSIGN statement, 2-16 Controlled job, 4-12 
ATTACHED condition, 7-119 Controlling job, 4-12 
Attaching SYS calls, 7-77 Conventions, programming, 8-1 


COUNT modifier, 2-12 
CR (carriage return), 3-2 
Creating user accounts, 7-60 


BACKSPACE, 4-9, 4-11 CTRL/C trap, 7-36 
Backspace function, 2-15 CTRL/O, cancelling, 7-3 
Bad tape (PARITY) error, 2-21 Cursor control, VT05, 4-9 
Baud rate, 7-66 Cursor control, vT50, 4-10 
Beginning-of-tape (BOT), 2-15 CURSOR DOWN, 4-9, 4-11 
BELL, 3-1 CURSOR RIGHT, 4-9, 4-11 
Binary data output, 4-1 CURSOR UP, 4-9, 4-11 


Binary input, 4-3 
Binary read mode, 6-4 
Bit, output parity, 7-66 


Block size, 2-6 Data changing, 7-39 

BOT (beginning-of-tape), 2-15 Dataset, 7-40 
Broadcasting, 7-41 Deassigning device, 7-32 
Buffer size, default, 1-17 Deassigning devices, 7-74 


Declaring a receiver, 7-82 
DECtape, non-file structured, 5-1 
Default buffer size, 1-17 


Calls, reattaching, 7-79 DEL (delete), 3-2 

Cancelling CTRL/O, 7-3 Delete (DEL), 3-2 

Card codes, punched, B-1l Deleted data marks, 1-16 

Carriage return (CR), 3-2 Deleting user accounts, 7-62 

CATALOG system command, 7-96 Density, 2-15 

CCL commands, 8-3 mMagtape, 2-10 

Changing, Density examples, 2-18 
date, 7-39 Deselect (DSEL), 3-2 
time, 7-39 DETACHED condition, 7-119 

Changing file statistics, 7-70 Detaching SYS calls, 7-75 

Changing passwords, 7-49 Device assigning, 7~30 

Changing quotas, 7-49 Device cluster, 1-10 

Channels, closing, 7-74 Device deassignment, 7-32 

Character, ESC CHRS$(27%), 7-68 Device zeroing, 7-34 


Character, up-arrow (* or +), 7-67 Device, deassign, 7-74 


INDEX-1 


Direct cursor control, 4-9 
Difference between LET and LSET, 
8-9 
Directory cluster size, 1-6 
Directory, 
disk, 7-100 
disk wild card, 7-101 
general guidelines, 7-101 
magtape, 7-97 
Directory look up, 7-94 
Disabling, 
echoing, 7-5 
logins, 7-43 
terminals, 7-52 
Disk, 
mounted, 1-11 
non-file structured, 1-10 
Disk directory, 7-100 
Disk pack status, 7-45 
Disk packs, cleaning, 7-48 
Disk storage, 1-2 
Disk wild card directory, 7-101 
DOS label, 2-3, 2-7 
DOS labels, A-3 
DOS magtape files, A-1l 
Dropping privileges, 7-59 
DSEL (deselect), 3-2 
Dump mode, 2-11 


Echoing, disabling, 7-5 
Editing strings, 7-20 
Eligible receiver, 7-84 
ELONG (elongated character), 3- 
Elongated character (ELONG), 3- 
END statement, 7-7 
EOF record, 2-14 
ERASE EOL, 4-9, 4-11 
ERASE EOS, 4-9, 4-11 
Error handling, 
example, 3-6 
line printer, 3-6 
Magtape, 2-21 
Error messages, 
non-recoverable, E-7 
recoverable, E-1 
ESCape sequences, 4-8 
ESC CHRS$(27%) character, 7-68 
ESC SEQ mode, 4-8 


2 
2 


Example, 
file characteristics, 2-19 
fragmenting job space, 7-115 


line printer error handling, 3-6 


pseudo keyboard, 4-14 
OPEN FOR OUTPUT statement, 2-7 
UPDATE, 1-13 
Examples, 
denisty, 2-18 
specifying read modes, 6-6 


Exiting to editor, 7-9 
Extending files, 2-6 
Extracting single strings, 7-7 


File characteristics, 
example, 2-19 
function, 2-18 
Files, extending, 2-6 
FILESIZE option, 2-6 
File statistics, changing, 7-70 
File structured magtape CLOSE, 2-9 
File structured magtape OPEN, 2-9 
File structured magtape OPEN FOR 
INPUT, 2-1 
File structured magtape OPEN FOR 
OUTPUT, 2-4 
Fill factor, 7-66 
FIP call notation, 7-14 
FIP code, 7-10 
FIP SYS calls, summary, 7-18 
First-in, first-output (FIFO) basis, 
7-81 
Fixed locations, monitor, 7-118 
Floppy disks, 1-14 
Forcing input, 7-42 
Form feed (FF), 3-2, 7-64 
Forms, non-standard length, 3-3 
Fragmenting job space, example, 
7-115 
Full duplex, 4-10 


General format, SYS functions, 7-1 
General guidelines, directory, 7-103 


Hold Screen Mode, 4-11 
HOME UP, 4-9, 4-11 
Horizontal tab (TAB), 3-1 


Input ESCape sequences, 4-8 
forcing, 7-42 
Interleaving algorithm, 1-15 


Job scheduling, 7-54 


KCT's (kilo-core-ticks), 1-2 
Killing jobs, 7-51 

KILL statement, 2-22 
Kilo-core-ticks, (KCT's), 1-2 
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Label, magtape, 
ANSI, 2-3, 2-7, A=-5 
DOS, 2-3, 2-7, A-3 
formats, A-l 
LET AND LSET, difference between, 
8-9 
Library account, system, 1-1, 1-3 
Line feed (LF), 3-1 
Line printer, 
error handling, 3-6 
LP1ll, 3-1 
LS11, 3-1 
Special operations, 3-2 
Loading, 
address, 7-115 
run-time systems, 7-114 
single strings, 7-8 
Locking jobs, 7-58 
Logged out terminals, 8-2 
LOGIN system program, 4-13, 8-2, 
8-3 
Logins, 
allowable setting, 7-89 
disabling, 7-43 
LOGIN SYS call, 7-72 
LOGIN system program, 1-1 
Logout, shutup, 7-38 
LOGOUT, 
system program, 1-2 
SYS call, 7-74 
Lower case 
characters, 7-64 
printing, 3-2 
translating, 7-66 
LP1l line printer, 3-1 
LS11 line printer, 3-1 


Magtape advancing, 2-14 
Magtape CLOSE, 

file structured, 2-9 

non-file structured, 2-10 
Magtape density, 2-10 
Magtape directory, 7-97 
Magtape error handling, 2-21 
Magtape, file structured, 

open for input, 2-1 

open for output, 2-4 
Magtape, 

7-track, 2-10 

9-track, 2-10 
Magtape file, 

ANSI, A-4 

DOS, A-1 
MAGTAPE function, 2-13 
Magtape label formats, A-1 
Magtape non-file structured, 2-13 
Magtape OPEN, 

file structured, 2-9 

non-file structured, 2-9 


Magtape parity, 
even, 2-10 
odd, 2-10 
Magtape phase encoding, 2-10 
Magtape rewinding, 2-13, 2-14 
Magtapes, zeroing, A-11l 
Master File Directory (MFD), 1-1 
Master terminal, 4-5 
Message sending, 7-85 
Messages, 
receiving, 7-81 
sending, 7-81 
Messages, error, 
non-recoverable, E-7 
recoverable, E-1 
MFD (Master File Directory), 1-1 
Minimum length records, 2-9 
Mode, ASCII, 6-1 
MODE specification, 2-4 
Magtape, 2-2 
MODE 5%, 1-13 
MODE 1%, 1-11 
MODE 16384%, 1-13 
MODE 2%, 1-13 
MONEY system program, 1-2 
Monitor, 7-88, 7-117 
fixed locations, 7-118 
Monitor table, 7-104 
Multiple users, 1-11 
Multiple terminal input, 4-6 
Multiple terminals, 4-5 


NAME AS statement, 2-22 

Naming run-time systems, 7-110 

9-track magtape, 2-10 

NO ESC SEQ mode, 4-8 

NONAME program, 7-9 

Non-file structured DECtape, 5-1 

Non-file structured disk, 1-10 

Non-file structured magtape, 2-13 

Non-file structured magtape CLOSE, 
2-10 

Non-file structured magtape OPEN, 
2-9 

Non-recoverable error messages, E-7 

Non-standard length forms, 3-3 


Off-line error, 2-22 
Off-line function, 2-13 
OPEN, 
file structured magtape, 2-9 
non-file structured magtape, 2-9 
Open for input, file structured 
mMagtape, 2-1 
Open for output, file structured 
mMagtape, 2-4 
Output ESCape sequences, 4-8 
Output parity bit, 7-66 
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Pack cluster size, 1-6 


Packed Hollerith read mode, 6-3 


Parity, 2-15 
Parity, magtape, 

even, 2-10 

odd, 2-10 
PARITY (Bad Tape) error, 2-21 
Password, 1-2 
Passwords, changing, 7-49 
PEEK function, 7-117 
Phase encoded, 2-15 
Phase encoding, magtape, 2-10 
Poke core, 7-88 
Pseudo keyboard, 4-12 
Printing special mode, 

G's as O's, 3-4 
Privilege, 1-8 
Privileged features, 1-9 
Privilege dropping, 7-59 


Privileged utility SYS calls, 7-38 


Programming conventions, 8-1 
Programming hints, 8-4 


Project-programmer number, 7-118 
Project-programmer number (account), 


1-2 
Protection code, 1-8 
Punched card codes, B-l 


Quota, 1-2 
Quotas, changing, 7-49 


RADIX-50 characters, C-l 
REACT system program, 1-1 
Reattaching SYS calls, 7-79 
Record I/O statement, 4-1 
REACT system program, 7-63 
Receivers, removing, 7-87 
Receiving messages, 7-81 
Record length error, 2-21 
RECORD option, 4-13 
Records, 
minimum length, 2-9 
releasing, 1-12 
searching, 2-5 
searching for, 2-2 
unlocking, 1-12 
writing, 2-5 
RECORDSIZE option, 2-12 
Record size, 2-6 
RECOUNT variable, 1-16, 2-12, 
7-28 


Recoverable error messages, E-1l 


Releasing records, 1-12 
Removing receivers, 7-87 


Removing run-time systems, 7-113 


Return file characteristics function, 
2-18 

Rewind function, 2-14 
Rewinding magtape, 2-13, 2-14 
Rewinding tape, 2-2, 2-6 
Rewind on CLOSE function, 2-20 
Run priority, setting, 7-56 
Run-time systems, 

adding, 7-111 

loading, 7-114 

naming, 7-110 

removing, 7-113 

unloading, 7-116 


SAT (Storage Allocation Table), 1-5 
Scheduling jobs, 7-54 
Searching for records, 2-5 
SEL (select), 3-2 
Select (SEL), 3-2 
Sending messages, 7-81, 7-85 
SEND operation, 7-86 
Setting allowable logins, 7-89 
Setting read modes, 6-5 
Setting run priority, 7-56 
Setting terminal characteristics, 
7-64 

7-track magtape, 2-10 
Shutup logout, 7-38 
SHUTUP system program, 7-113 
Simultaneous user access, 1-11 
Single character input, 7-6 
Skip record function, 2-14 
Slave terminal, 4-5 
Small buffers, 3-5, 7-81 
Software formatting, 3-4 
Special line printer operations, 3-2 
Statistics, file, 

changing, 7-70 
Status, 

disk pack, 7-45 

terminal, 7-45 
Status variable, 7-28 
Status word, 2-17 
Storage Allocation Table (SAT), 

1-5 

Storage space, 8-4 
String editing, 7-20 
String manipulation, 8-9 
Summary of FIP SYS calls, 7-18 
Swap maximum, 8-3 
SWAP% function, 7-12 
Synchronization, 7-67 
SYS call, LOGIN, 7-72 

LOGOUT, 7-74 
SYS calls, 

attaching, 7-77 

detaching, 7-75 

privileged utility, 7-38 

utility, 7-20 
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SYS system function calls, 7-1 Variable RECOUNT, 7-28 
SYS system function formats, 7-1 Vertical tab, 3-1, 7-64 
System accounts, i-i VTO5 cursor control, 4-9 
System function calls, SYS, 7-1 VT50 cursor control, 4-10 
System library account, 1-1, 1-3 
System program, 

LOGIN, 1-1, 8-2, 8-3 


LOGOUT, 1-2 Wild card directory, disk, 7-101 
MONEY, 1-2 Write lock error, 2-22 
REACT, 1-1, 7-63 Writing records, 2-5 


SHUTUP, 7-113 
UTILITY, 1-2 


XOFF characters, 7-65 
XON characters, 7-65 
Tab, 
horizontal (TAB), 3-1 
vertical (VT), 3-1 


Table, monitor, 7-104 Zero (f§) characters, printing as 
TAPE command, 7-3 O characters, 3-4 
Tape status function, 2-16 Zeroing, 
Terminal, devices, 7-34 
characteristics, 7-64 Magtapes, A~ll 


disabling, 7-52 
logged out, 8-2 
status, 7-45 
Translating lower case characters, 
7-66 
Trap, CTRL/C, 7-36 
Truncating lines, 3-4 
TU1O drive, 2-10 
TU16 drive, 2-10 


Unloading run-time systems, 7-116 
Unlocking records, 1~-12 
Up arrow (* or + ) character, 
7-67 
UPDATE option, 1-11 
User accounts, 
creating, 7-60 
deleting, 7-62 
User File Directory (UFD), 1-1 
Utility SYS calls, 7-20 
privileged, 7-38 
UTILITY system program, 1-2 
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